XEP-0045: Multi-User Chat

Transcription

1 XEP-0045: Multi-User Chat Peter Saint-Andre Version 1.29 Status Type Short Name Draft Standards Track muc This specification defines an XMPP protocol extension for multi-user text chat, whereby multiple XMPP users can exchange messages in the context of a room or channel, similar to Internet Relay Chat (IRC). In addition to standard chatroom features such as room topics and invitations, the protocol defines a strong room control model, including the ability to kick and ban users, to name room moderators and administrators, to require membership or passwords in order to join the room, etc.

2 Legal Copyright This XMPP Extension Protocol is copyright by the XMPP Standards Foundation (XSF). Permissions Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the Specification ), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. Warranty ## NOTE WELL: This Specification is provided on an AS IS BASIS, WITHOUT WARRANTIES OR CONDI- TIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ## Liability In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. Conformance This XMPP Extension Protocol has been contributed in full conformance with the XSF s Intellectual Property Rights Policy (a copy of which can be found at < or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO USA).

3 Contents 1 Introduction 1 2 Scope 1 3 Requirements 2 4 Terminology General Terms Room Types Dramatis Personae Roles, Affiliations, and Privileges Roles Privileges Default Roles Changing Roles Affiliations Privileges Changing Affiliations Entity Use Cases Discovering a MUC Service Discovering the Features Supported by a MUC Service Discovering Rooms Querying for Room Information Querying for Room Items Querying a Room Occupant Discovering Client Support for MUC Occupant Use Cases Order of Events Entering a Room Groupchat 1.0 Protocol Basic MUC Protocol Presence Broadcast Non-Anonymous Rooms Semi-Anonymous Rooms Password-Protected Rooms Members-Only Rooms Banned Users Nickname Conflict Max Users Locked Room

4 Nonexistent Room Room Logging Discussion History Managing Discussion History Room Subject Live Messages Error Conditions Occupant Modification of the Room Subject Sending a Message to All Occupants Sending a Private Message Changing Nickname Changing Availability Status Inviting Another User to a Room Direct Invitation Mediated Invitation Converting a One-to-One Chat Into a Multi-User Conference Registering with a Room Getting the Member List Discovering Reserved Room Nickname Requesting Voice Exiting a Room Moderator Use Cases Modifying the Room Subject Kicking an Occupant Granting Voice to a Visitor Revoking Voice from a Participant Modifying the Voice List Approving Voice Requests Admin Use Cases Banning a User Modifying the Ban List Granting Membership Revoking Membership Modifying the Member List Granting Moderator Status Revoking Moderator Status Modifying the Moderator List Approving Registration Requests Owner Use Cases Creating a Room General Considerations

5 Creating an Instant Room Creating a Reserved Room Subsequent Room Configuration Notification of Configuration Changes Granting Owner Status Revoking Owner Status Modifying the Owner List Granting Admin Status Revoking Admin Status Modifying the Admin List Destroying a Room Status Codes Internationalization Considerations Security Considerations User Authentication and Authorization End-to-End Encryption Privacy Information Leaks Anonymity Denial of Service Other Considerations IANA Considerations XMPP Registrar Considerations Protocol Namespaces Service Discovery Category/Type Service Discovery Features Well-Known Service Discovery Nodes Field Standardization muc#register FORM_TYPE muc#request FORM_TYPE muc#roomconfig FORM_TYPE muc#roominfo FORM_TYPE Status Codes Registry Process Initial Submission URI Query Types join invite

6 16 Business Rules Addresses Message Presence IQ Implementation Notes Services Allowable Traffic Ghost Users Clients IRC Command Mapping Presence Subscriptions XML Schemas Acknowledgements 154

7 2 SCOPE 1 Introduction Traditionally, instant messaging is thought to consist of one-to-one chat rather than manyto-many chat, which is called variously groupchat or text conferencing. Groupchat functionality is familiar from systems such as Internet Relay Chat (IRC) and the chatroom functionality offered by popular consumer IM services. The Jabber/XMPP community developed and implemented a basic groupchat protocol as long ago as That groupchat 1.0 (GC) protocol provided a minimal feature set for chat rooms but was rather limited in scope. This specification (Multi-User Chat or MUC) builds on the older groupchat 1.0 protocol in a backwards-compatible manner but provides advanced features such as invitations, room moderation and administration, and specialized room types. 2 Scope This document addresses common requirements related to configuration of, participation in, and administration of individual text-based conference rooms. All of the requirements addressed herein apply at the level of the individual room and are common in the sense that they have been widely discussed within the Jabber/XMPP community or are familiar from existing text-based conference environments (e.g., Internet Relay Chat as defined in RFC and its successors: RFC , RFC , RFC , RFC ). This document explicitly does not address the following: Relationships between rooms (e.g., hierarchies of rooms) Management of multi-user chat services (e.g., managing permissions across an entire service or registering a global room nickname); such use cases are specified in Service Administration (XEP-0133) 6 Moderation of individual messages Encryption of messages sent through a room Advanced features such as attaching files to a room, integrating whiteboards, and using MUC rooms as a way to manage the signalling for multi-user audio or video conferencing (see Multiparty Jingle (XEP-0272) 7 ) Interaction between MUC deployments and foreign chat systems (e.g., gateways to IRC or to legacy IM systems) 1 RFC 1459: Internet Relay Chat < 2 RFC 2810: Internet Relay Chat: Architecture < 3 RFC 2811: Internet Relay Chat: Channel Management < 4 RFC 2812: Internet Relay Chat: Client Protocol < 5 RFC 2813: Internet Relay Chat: Server Protocol < 6 XEP-0133: Service Administration < 7 XEP-0272: Multiparty Jingle < 1

8 3 REQUIREMENTS Mirroring or replication of rooms among multiple MUC deployments This limited scope is not meant to disparage such topics, which are of inherent interest; however, it is meant to focus the discussion in this document and to present a comprehensible protocol that can be implemented by client and service developers alike. Future specifications might address the topics mentioned above. 3 Requirements This document addresses the minimal functionality provided by Jabber-based multi-user chat services that existed in 2002 when development of MUC began. For the sake of backwardscompatibility, this document uses the original groupchat 1.0 protocol for this baseline functionality, with the result that: Each room is identified as a room JID <room@service> (e.g., <jdev@conference.jabber.org>), where room is the name of the room and service is the hostname at which the multi-user chat service is running. Each occupant in a room is identified as an occupant JID <room@service/nick>, where nick is the room nickname of the occupant as specified on entering the room or subsequently changed during the occupant s visit. A user enters a room (i.e., becomes an occupant) by sending directed presence to <room@service/nick>. An occupant can change his or her room nickname and availability status within the room by sending presence information to <room@service/newnick>. Messages sent within multi-user chat rooms are of a special type groupchat and are addressed to the room itself (room@service), then reflected to all occupants. An occupant exits a room by sending presence of type unavailable to its current <room@service/nick>. The additional features and functionality addressed in MUC include the following: 1. native conversation logging (no in-room bot required) 2. enabling users to request membership in a room 3. enabling occupants to view an occupant s full JID in a non-anonymous room 4. enabling moderators to view an occupant s full JID in a semi-anonymous room 5. allowing only moderators to change the room subject 2

9 4 TERMINOLOGY 6. enabling moderators to kick participants and visitors from the room 7. enabling moderators to grant and revoke voice (i.e., the privilege to speak) in a moderated room, and to manage the voice list 8. enabling admins to grant and revoke moderator status, and to manage the moderator list 9. enabling admins to ban users from the room, and to manage the ban list 10. enabling admins to grant and revoke membership privileges, and to manage the member list for a members-only room 11. enabling owners to configure various room parameters (e.g., limiting the number of occupants) 12. enabling owners to specify other owners 13. enabling owners to grant and revoke admin status, and to manage the admin list 14. enabling owners to destroy the room In addition, this document provides protocol elements for supporting the following room types: 1. public vs. hidden 2. persistent vs. temporary 3. password-protected vs. unsecured 4. members-only vs. open 5. moderated vs. unmoderated 6. non-anonymous vs. semi-anonymous The extensions needed to implement these requirements are qualified by the namespace (and the #owner, #admin, and #user fragments on the main namespace URI). 4 Terminology 4.1 General Terms Affiliation A long-lived association or connection with a room; the possible affiliations are owner, admin, member, and outcast (naturally it is also possible to have no affiliation); affiliation is distinct from role. An affiliation lasts across a user s visits to a room. 3

10 4 TERMINOLOGY Ban To remove a user from a room such that the user is not allowed to re-enter the room (until and unless the ban has been removed). A banned user has an affiliation of outcast. Bare JID The <user@host> by which a user is identified outside the context of any existing session or resource; contrast with Full JID and Occupant JID. Full JID The <user@host/resource> by which an online user is identified outside the context of a room; contrast with Bare JID and Occupant JID. GC The minimal groupchat 1.0 protocol developed within the Jabber community in 1999; MUC is backwards-compatible with GC. History A limited number of message stanzas sent to a new occupant to provide the context of current discussion. Invitation A special message sent from one user to another asking the recipient to join a room; the invitation can be sent directly (see Direct MUC Invitations (XEP-0249) XEP- 0249: Direct MUC Invitations < or mediated through the room (as described under Inviting Another User to a Room). IRC Internet Relay Chat. Kick To temporarily remove a participant or visitor from a room; the user is allowed to reenter the room at any time. A kicked user has a role of none. Logging Storage of discussions that occur within a room for public retrieval outside the context of the room. Member A user who is on the whitelist for a members-only room or who is registered with an open room. A member has an affiliation of member. Moderator A room role that is usually associated with room admins but that can be granted to non-admins; is allowed to kick users, grant and revoke voice, etc. A moderator has a role of moderator. MUC The multi-user chat protocol for text-based conferencing specified in this document. Multi-Session Nick If allowed by the service, a user can associate more than one full JID with the same occupant JID (e.g., the user juliet@capulet.lit is allowed to log in simultaneously as the nick JuliC in the characters@chat.shakespeare.lit chatroom from both juliet@capulet.lit/balcony and juliet@capulet.lit/chamber). Multi-session nicks are not currently defined in this document. Occupant Any user who is in a room (this is an abstract class and does not correspond to any specific role). Occupant JID The <room@service/nick> by which an occupant is identified within the context of a room; contrast with Bare JID and Full JID. 4

11 4 TERMINOLOGY Outcast A user who has been banned from a room. An outcast has an affiliation of outcast. Participant An occupant who does not have admin status; in a moderated room, a participant is further defined as having voice (in contrast to a visitor). A participant has a role of participant. Private Message A message sent from one occupant directly to another s occupant JID (not to the room itself for broadcasting to all occupants). Role A temporary position or privilege level within a room, distinct from a user s long-lived affiliation with the room; the possible roles are moderator, participant, and visitor (it is also possible to have no defined role). A role lasts only for the duration of an occupant s visit to a room. Room A virtual space that users figuratively enter in order to participate in real-time, textbased conferencing with other users. Room Administrator A user empowered by the room owner to perform administrative functions such as banning users; however, a room administrator is not allowed to change the room configuration or to destroy the room. An admin has an affiliation of admin. Room ID The localpart of a Room JID, which might be opaque and thus lack meaning for human users (see under Business Rules for syntax); contrast with Room Name. Room JID The <room@service> address of a room. Room Name A user-friendly, natural-language name for a room, configured by the room owner and presented in Service Discovery queries; contrast with Room ID. Room Nickname The resourcepart of an Occupant JID (see Business Rules for syntax); this is the friendly name by which an occupant is known in the room. Room Owner The user who created the room or a user who has been designated by the room creator or owner as someone with owner status (if allowed); an owner is allowed to change the room configuration and destroy the room, in addition to all admin status. An owner has an affiliation of owner. Room Roster A client s representation of the occupants in a room. Server An XMPP server that may or may not have associated with it a text-based conferencing service. Service A host that offers text-based conferencing capabilities; often but not necessarily a sub-domain of an XMPP server (e.g., conference.jabber.org). Subject A temporary discussion topic within a room. Visit A user s session in a room, beginning when the user enters the room (i.e., becomes an occupant) and ending when the user exits the room. 5

12 4 TERMINOLOGY Visitor In a moderated room, an occupant who does not have voice (in contrast to a participant). A visitor has a role of visitor. Voice In a moderated room, the privilege to send messages to all occupants. 4.2 Room Types Hidden Room A room that cannot be found by any user through normal means such as searching and service discovery; antonym: Public Room. Members-Only Room A room that a user cannot enter without being on the member list; antonym: Open Room. Moderated Room A room in which only those with voice are allowed to send messages to all occupants; antonym: Unmoderated Room. Non-Anonymous Room A room in which an occupant s full JID is exposed to all other occupants, although the occupant can request any desired room nickname; contrast with Semi-Anonymous Room. Open Room A room that non-banned entities are allowed to enter without being on the member list; antonym: Members-Only Room. Password-Protected Room A room that a user cannot enter without first providing the correct password; antonym: Unsecured Room. Persistent Room A room that is not destroyed if the last occupant exits; antonym: Temporary Room. Public Room A room that can be found by any user through normal means such as searching and service discovery; antonym: Hidden Room. Semi-Anonymous Room A room in which an occupant s full JID can be discovered by room admins only; contrast with Non-Anonymous Room. Temporary Room A room that is destroyed if the last occupant exits; antonym: Persistent Room. Unmoderated Room A room in which any occupant is allowed to send messages to all occupants; antonym: Moderated Room. Unsecured Room A room that anyone is allowed to enter without first providing the correct password; antonym: Password-Protected Room. 6

13 4 TERMINOLOGY 4.3 Dramatis Personae Most of the examples in this document use the scenario of the witches meeting held in a dark cave at the beginning of Act IV, Scene I of Shakespeare s Macbeth, represented here as the coven@chat.shakespeare.lit chatroom. The characters are as follows: 7

14 5 ROLES, AFFILIATIONS, AND PRIVILEGES Room Nickname Full JID Affiliation firstwitch Owner secondwitch Admin thirdwitch None 5 Roles, Affiliations, and Privileges A user might be allowed to perform any number of actions in a room, from joining or sending a message to changing configuration options or destroying the room altogether. We call each permitted action a privilege. There are two ways we might structure privileges: 1. Define each privilege atomically and explicitly define each user s particular privileges; this is flexible but can be confusing to manage. 2. Define bundles of privileges that are generally applicable and assign a user-friendly shortcut to each bundle (e.g., moderator or admin ). MUC takes the second approach. MUC also defines two different associations: long-lived affiliations and session-specific roles. These two association types are distinct from each other in MUC, since an affiliation lasts across visits, while a role lasts only for the duration of a visit. In addition, there is no one-to-one correspondence between roles and affiliations; for example, someone who is not affiliated with a room may be a (temporary) moderator, and a member may be a participant or a visitor in a moderated room. These concepts are explained more fully below. 5.1 Roles The following roles are defined: Name Moderator None Participant Visitor Support REQUIRED N/A (the absence of a role) REQUIRED RECOMMENDED 8

15 5 ROLES, AFFILIATIONS, AND PRIVILEGES Roles are temporary in that they do not necessarily persist across a user s visits to the room and MAY change during the course of an occupant s visit to the room. An implementation MAY persist roles across visits and SHOULD do so for moderated rooms (since the distinction between visitor and participant is critical to the functioning of a moderated room). There is no one-to-one mapping between roles and affiliations (e.g., a member could be a participant or a visitor). A moderator is the most powerful role within the context of the room, and can to some extent manage other occupants roles in the room. A participant has fewer privileges than a moderator, although he or she always has the right to speak. A visitor is a more restricted role within the context of a moderated room, since visitors are not allowed to send messages to all occupants (depending on room configuration, it is even possible that visitors presence will not be broadcasted to the room). Roles are granted, revoked, and maintained based on the occupant s room nickname or full JID rather than bare JID. The privileges associated with these roles, as well as the actions that trigger changes in roles, are defined below. Information about roles MUST be sent in all presence stanzas generated or reflected by the room and thus sent to occupants (if the room is configured to broadcast presence for a given role) Privileges For the most part, roles exist in a hierarchy. For instance, a participant can do anything a visitor can do, and a moderator can do anything a participant can do. Each role has all the privileges possessed by the next-lowest role, plus additional privileges; these privileges are specified in the following table as defaults (an implementation MAY provide configuration options that override these defaults). Privilege None Visitor Participant Moderator Present in Room No Yes Yes Yes Receive Messages No Yes Yes Yes Receive Occupant Presence No Yes Yes Yes Broadcast Presence to All Occupants No Yes* Yes Yes Change Availability Status No Yes* Yes Yes Change Room Nickname No Yes* Yes Yes Send Private Messages No Yes* Yes Yes Invite Other Users No Yes* Yes* Yes Send Messages to All No No** Yes Yes Modify Subject No No* Yes* Yes Kick Participants and Visitors No No No Yes Grant Voice No No No Yes Revoke Voice No No No Yes*** 9

16 5 ROLES, AFFILIATIONS, AND PRIVILEGES * Default; configuration settings MAY modify this privilege. * An implementation MAY grant voice by default to visitors in unmoderated rooms. ** A moderator MUST NOT be able to revoke voice privileges from an admin or owner Default Roles The following table summarizes the initial default roles that a service SHOULD set based on the user s affiliation (there is no role associated with the outcast affiliation, since such users are not allowed to enter the room). Room Type None Member Admin Owner Moderated Visitor Participant Moderator Moderator Unmoderated Participant Participant Moderator Moderator Members-Only N/A * Participant Moderator Moderator Open Participant Participant Moderator Moderator * Entry is not permitted Changing Roles The ways in which an occupant s role changes are well-defined. Sometimes the change results from the occupant s own action (e.g., entering or exiting the room), whereas sometimes the change results from an action taken by a moderator, admin, or owner. If an occupant s role changes, a MUC service implementation MUST change the occupant s role to reflect the change and communicate the change to all occupants (if the room is configured to broadcast presence from entities with a given role). Role changes and their triggering actions are specified in the following table. > None Visitor Participant Moderator None -- Enter moderated Enter unmoderated Admin or owner Visitor Exit room or be room -- room Moderator enters room Admin or owner kicked by a moderator grants voice grants moderator Participant Exit room or be Moderator -- status Admin or owner kicked by a moderatotor revokes voice grants modera- status 10

17 5 ROLES, AFFILIATIONS, AND PRIVILEGES > None Visitor Participant Moderator Moderator Exit room or be kicked by an admin or owner * Admin or owner changes role to visitor * Admin or owner changes role to participant or revokes moderator status * -- * A moderator SHOULD NOT be allowed to revoke moderation privileges from someone with a higher affiliation than themselves (i.e., an unaffiliated moderator SHOULD NOT be allowed to revoke moderation privileges from an admin or an owner, and an admin SHOULD NOT be allowed to revoke moderation privileges from an owner). Note: Certain roles are typically implicit in certain affiliations. For example, an admin or owner is automatically a moderator, so if an occupant is granted an affiliation of admin then the occupant will by that fact be granted a role of moderator; similarly, when an occupant is granted an affiliation of member in a moderated room, the occupant automatically has a role of participant. However, the loss of the admin affiliation does not necessarily mean that the occupant no longer has a role of moderator (since a mere occupant can be a moderator). Therefore, the role that is gained when an occupant is granted a certain affiliation is stable, whereas the role that is lost when an occupant loses a certain affilitation is not hardcoded and is left up to the implementation. 5.2 Affiliations The following affiliations are defined: 1. Owner 2. Admin 3. Member 4. Outcast 5. None (the absence of an affiliation) Support for the owner affiliation is REQUIRED. Support for the admin, member, and outcast affiliations is RECOMMENDED. (The None affiliation is the absence of an affiliation.) These affiliations are long-lived in that they persist across a user s visits to the room and are not affected by happenings in the room. In addition, there is no one-to-one mapping between these affiliations and an occupant s role within the room. Affiliations are granted, revoked, and maintained based on the user s bare JID, not the nick as with roles. If a user without a defined affiliation enters a room, the user s affiliation is defined as none ; however, this affiliation does not persist across visits (i.e., a service does not maintain a none 11

18 5 ROLES, AFFILIATIONS, AND PRIVILEGES list across visits). The member affiliation provides a way for a room owner or admin to specify a whitelist of users who are allowed to enter a members-only room. When a member enters a members-only room, his or her affiliation does not change, no matter what his or her role is. The member affiliation also provides a way for users to register with an open room and thus be lastingly associated with that room in some way (one result might be that the service could reserve the user s nickname in the room). An outcast is a user who has been banned from a room and who is not allowed to enter the room. Information about affiliations MUST be sent in all presence stanzas generated or reflected by the room and sent to occupants (if the room is configured to broadcast presence from entities with a given role) Privileges For the most part, affiliations exist in a hierarchy. For instance, an owner can do anything an admin can do, and an admin can do anything a member can do. Each affiliation has all the privileges possessed by the next-lowest affiliation, plus additional privileges; these privileges are specified in the following table. Privilege Outcast None Member Admin Owner Enter Open Room No Yes* Yes Yes Yes Register with Open Room No Yes N/A N/A N/A Retrieve Member List No No Yes Yes Yes Enter Members-Only Room No No Yes* Yes Yes Ban Members and Unaffiliated Users No No No Yes Yes Edit Member List No No No Yes Yes Assign and Remove Moderator Role No No No Yes** Yes** Edit Admin List No No No No Yes Edit Owner List No No No No Yes Change Room Configuration No No No No Yes Destroy Room No No No No Yes * As a default, an unaffiliated user enters a moderated room as a visitor, and enters an open room as a participant. A member enters a room as a participant. An admin or owner enters a room as a moderator. * As noted, a moderator SHOULD NOT be allowed to revoke moderation privileges from someone with a higher affiliation than themselves (i.e., an unaffiliated moderator SHOULD NOT be allowed to revoke moderation privileges from an admin or an owner, and an admin SHOULD NOT be allowed to revoke moderation privileges from an owner). 12

19 5 ROLES, AFFILIATIONS, AND PRIVILEGES Changing Affiliations The ways in which a user s affiliation changes are well-defined. Sometimes the change results from the user s own action (e.g., registering as a member of the room), whereas sometimes the change results from an action taken by an admin or owner. If a user s affiliation changes, a MUC service implementation MUST change the user s affiliation to reflect the change and communicate that to all occupants (if the room is configured to broadcast presence from entities with a given role). Affiliation changes and their triggering actions are specified in the following table. > Outcast None Member Admin Owner Outcast -- Admin or Admin or Owner adds Owner adds owner removes owner adds user to admin user to owner ban user to list list None Admin or -- member list Admin or Owner adds Owner adds owner applies owner adds user to admin user to owner ban user to mem- list list ber list, or user registers as member (if allowed) Member Admin or owner applies ban Admin Owner applies ban Owner Owner applies ban Admin or owner changes affiliation to none Owner changes affiliation to none Owner changes affiliation to none -- Owner adds user to admin list Owner changes affiliation to member Owner changes affiliation to member Owner adds user to owner list -- Owner adds user to owner list af- to Owner changes filiation admin -- 13

20 6 ENTITY USE CASES 6 Entity Use Cases A MUC implementation MUST support Service Discovery (XEP-0030) 8 ( disco ). Any entity can complete the following disco-related use cases. 6.1 Discovering a MUC Service An entity often discovers a MUC service by sending a Service Discovery items ( disco#items ) request to its own server. Listing 1: Entity Queries Server for Associated Services <iq from = hag66@shakespeare.lit /pda id= h7ns81g to= shakespeare.lit type = get > <query xmlns = http: // jabber.org / protocol / disco # items /> The server then returns the services that are associated with it. Listing 2: Server Returns Disco Items Result <iq from = shakespeare. lit id= h7ns81g to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items > <item jid = chat. shakespeare.lit name = Chatroom Service /> </ query > 6.2 Discovering the Features Supported by a MUC Service An entity may wish to discover if a service implements the Multi-User Chat protocol; in order to do so, it sends a service discovery information ( disco#info ) query to the MUC service s JID. Listing 3: Entity Queries Chat Service for MUC Support via Disco <iq from = hag66@shakespeare.lit /pda id= lx09df27 to= chat. shakespeare.lit type = get > 8 XEP-0030: Service Discovery < 14

21 6 ENTITY USE CASES <query xmlns = http: // jabber.org / protocol / disco # info /> The service MUST return its identity and the features it supports. Listing 4: Service Returns Disco Info Result <iq from = chat. shakespeare.lit id= lx09df27 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # info > <identity category = conference name = Shakespearean Chat Service type = text /> <feature var = http: // jabber.org / protocol /muc /> </ query > 6.3 Discovering Rooms The service discovery items ( disco#items ) protocol enables an entity to query a service for a list of associated items, which in the case of a chat service would consist of the specific chat rooms hosted by the service. Listing 5: Entity Queries Chat Service for Rooms <iq from = hag66@shakespeare.lit /pda id= zb8q41f4 to= chat. shakespeare.lit type = get > <query xmlns = http: // jabber.org / protocol / disco # items /> The service SHOULD return a full list of the public rooms it hosts (i.e., not return any rooms that are hidden). Listing 6: Service Returns Disco Items Result <iq from = chat. shakespeare.lit id= zb8q41f4 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items > <item jid = heath@chat. shakespeare.lit name = A Lonely Heath /> 15

22 6 ENTITY USE CASES <item jid = coven@chat. shakespeare.lit name = A Dark Cave /> <item jid = forres@chat. shakespeare.lit name = The Palace /> <item jid = inverness@chat. shakespeare.lit name = Macbeth & apos ;s Castle /> </ query > If the full list of rooms is large (see XEP-0030 for details), the service MAY return only a partial list of rooms. If it does so, it SHOULD include a <set/> element qualified by the namespace (as defined in Result Set Management (XEP- 0059) 9 ) to indicate that the list is not the full result set. Listing 7: Service Returns Limited List of Disco Items Result <iq from = chat. shakespeare.lit id= hx51v49s to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items > <item jid = alls -well -that -ends - well@chat. shakespeare.lit /> <item jid = as -you -like - it@chat. shakespeare.lit /> <item jid = cleopatra@chat. shakespeare.lit /> <item jid = comedy -of - errors@chat. shakespeare.lit /> <item jid = coriolanus@chat. shakespeare.lit /> <item jid = cymbeline@chat. shakespeare.lit /> <item jid = hamlet@chat. shakespeare.lit /> <item jid = henry -the -fourth - one@chat. shakespeare.lit /> <item jid = henry -the -fourth - two@chat. shakespeare.lit /> <item jid = henry -the - fifth@chat. shakespeare.lit /> <set xmlns = http: // jabber.org / protocol /rsm > <first index = 0 >alls -well -that -ends - well@chat. shakespeare.lit </ first > <last >henry -the - fifth@chat. shakespeare.lit </ last > <count >37 </ count > </ set > </ query > 6.4 Querying for Room Information Using the disco#info protocol, an entity may also query a specific chat room for more detailed information about the room. An entity SHOULD do so before entering a room in order to determine the privacy and security profile of the room configuration (see the Security 9 XEP-0059: Result Set Management < 16

23 6 ENTITY USE CASES Considerations for details). Listing 8: Entity Queries for Information about a Specific Chat Room <iq from = hag66@shakespeare.lit /pda id= ik3vs715 to= coven@chat. shakespeare.lit type = get > <query xmlns = http: // jabber.org / protocol / disco # info /> The room MUST return its identity and SHOULD return the features it supports: Listing 9: Room Returns Disco Info Result <iq from = coven@chat. shakespeare. lit id= ik3vs715 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # info > <identity category = conference name = A Dark Cave type = text /> <feature var = http: // jabber.org / protocol /muc /> < feature var = muc_ passwordprotected / > <feature var = muc_hidden /> <feature var = muc_temporary /> <feature var = muc_open /> <feature var = muc_unmoderated /> <feature var = muc_nonanonymous /> </ query > Note: The room SHOULD return the materially-relevant features it supports, such as password protection and room moderation (these are listed fully in the feature registry maintained by the XMPP Registrar; see also the XMPP Registrar section of this document). A chatroom MAY return more detailed information in its disco#info response using Service Discovery Extensions (XEP-0128) 10, identified by inclusion of a hidden FORM_TYPE field whose value is Such information might include a more verbose description of the room, the current room subject, and the current number of occupants in the room: Listing 10: Room Returns Extended Disco Info Result <iq from = coven@chat. shakespeare. lit 10 XEP-0128: Service Discovery Extensions < 17

24 6 ENTITY USE CASES id= ik3vs715 to= /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # info > <identity category = conference name = A Dark Cave type = text /> <feature var = http: // jabber.org / protocol /muc /> < feature var = muc_ passwordprotected / > <feature var = muc_hidden /> <feature var = muc_temporary /> <feature var = muc_open /> <feature var = muc_unmoderated /> <feature var = muc_nonanonymous /> <x xmlns = jabber:x:data type = result > var = FORM_TYPE type = hidden > <value >http: // jabber.org/ protocol /muc# roominfo </ value > var = muc # roominfo_description label = Description > < value > The place for all good witches! </ value > var = muc # roominfo_changesubject label = Occupants May Change the Subject > <value >true </ value > var = muc # roominfo_contactjid label = Contact Addresses > <value > crone1@shakespeare.lit </ value > var = muc # roominfo_subject label = Current Discussion Topic > <value >Spells </ value > var = muc # roomconfig_changesubject label = Subject can be modified > <value >true </ value > var = muc # roominfo_occupants label = Number of occupants > <value >3</ value > var = muc # roominfo_ldapgroup label = Associated LDAP Group > <value >cn= witches,dc= shakespeare,dc=lit </ value > var = muc # roominfo_lang label = Language of discussion > 18

25 6 ENTITY USE CASES <value >en </ value > var = muc # roominfo_logs label = URL for discussion logs > <value >http: // www. shakespeare.lit/ chatlogs / coven /</ value > var = muc # maxhistoryfetch label = Maximum Number of History Messages Returned by Room > <value >50 </ value > var = muc # roominfo_pubsub label = Associated pubsub node > <value >xmpp:pubsub. shakespeare.lit?; node =the -coven - node </ value > </ query > Some extended room information is dynamically generated (e.g., the URL for discussion logs, which may be based on service-wide configuration), whereas other information is based on the more-stable room configuration, which is why any field defined for the muc#roomconfig FORM_TYPE can be included in the extended service discovery fields (as shown above for the muc#roomconfig_changesubject field). Note: The foregoing extended service discovery fields for the FORM_TYPE are examples only and might be supplemented in the future via the mechanisms described in the Field Standardization section of this document. 6.5 Querying for Room Items An entity MAY also query a specific chat room for its associated items: Listing 11: Entity Queries for Items Associated with a Specific Chat Room <iq from = hag66@shakespeare.lit /pda id= kl2fax27 to= coven@chat. shakespeare.lit type = get > <query xmlns = http: // jabber.org / protocol / disco # items /> An implementation MAY return a list of existing occupants if that information is publicly available, or return no list at all if this information is kept private. Implementations and deployments are advised to turn off such information sharing by default. 19

26 6 ENTITY USE CASES Listing 12: Room Returns Disco Items Result (Items are Public) <iq from = coven@chat. shakespeare. lit id= kl2fax27 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items > <item jid = coven@chat. shakespeare.lit / firstwitch /> <item jid = coven@chat. shakespeare.lit / secondwitch /> </ query > Note: These <item/> elements are qualified by the disco#items namespace, not the muc namespace; this means that they cannot possess affiliation or role attributes, for example. If the list of occupants is private, the room MUST return an empty <query/> element, in accordance with XEP Listing 13: Room Returns Empty Disco Items Result (Items are Private) <iq from = coven@chat. shakespeare. lit id= kl2fax27 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items /> 6.6 Querying a Room Occupant If a non-occupant attempts to send a disco request to an address of the form <room@service/nick>, a MUC service MUST return a <bad-request/> error. If an occupant sends such a request, the service MAY pass it through the intended recipient; see the Implementation Guidelines section of this document for details. 6.7 Discovering Client Support for MUC An entity might want to discover if one of the entity s contacts supports the Multi-User Chat protocol (e.g., before attempting to invite the contact to a room). This can be done using Service Discovery. Listing 14: Entity Queries Contact Regarding MUC Support <iq from = hag66@shakespeare.lit /pda id= yh2fs843 to= wiccarocks@shakespeare.lit / laptop type = get > <query xmlns = http: // jabber.org / protocol / disco # info /> 20

27 6 ENTITY USE CASES The client SHOULD return its identity and the features it supports. Listing 15: Contact Returns Disco Info Result <iq from = wiccarocks@shakespeare. lit / laptop id= yh2fs843 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # info > <identity category = client type = pc />... <feature var = http: // jabber.org / protocol /muc />... </ query > An entity may also query a contact regarding which rooms the contact is in. This is done by querying the contact s full JID (<user@host/resource>) while specifying the well-known Service Discovery node Listing 16: Entity Queries Contact for Current Rooms <iq from = hag66@shakespeare.lit /pda id= gp7w61v3 to= wiccarocks@shakespeare.lit / laptop type = get > <query xmlns = http: // jabber.org / protocol / disco # items node = http: // jabber.org / protocol /muc # rooms /> Listing 17: Contact Returns Room Query Result <iq from = wiccarocks@shakespeare. lit / laptop id= gp7w61v3 to= hag66@shakespeare.lit /pda type = result > <query xmlns = http: // jabber.org / protocol / disco # items node = http: // jabber.org / protocol /muc # rooms > <item jid = coven@chat. shakespeare.lit /> <item jid = characters@conference. shakespeare.lit /> </ query > Optionally, the contact MAY include its roomnick as the value of the name attribute: 21

28 7 OCCUPANT USE CASES... <item jid = coven@chat. shakespeare.lit name = secondwitch />... If this information is private, the user MUST return an empty <query/> element, in accordance with XEP Occupant Use Cases The main actor in a multi-user chat environment is the occupant, who can be said to be located in a multi-user chat room and to participate in the discussions held in that room (for the purposes of this specification, participants and visitors are considered to be mere occupants, since they possess no admin status). As will become clear, the protocol elements proposed in this document to fulfill the occupant use cases fall into three categories: 1. the basic functionality for joining a room, exchanging messages with all occupants, etc. (supported by the groupchat 1.0 protocol that preceded MUC) 2. straightforward additions to the basic functionality, such as handling of errors related to new room types 3. additional protocol elements to handle functionality not covered by groupchat 1.0 (room invites, room passwords, extended presence related to room roles and affiliations); these are qualified by the namespace Note: All client-generated examples herein are presented from the perspective of the service, with the result that all stanzas received by a service contain a from attribute corresponding to the sender s full JID as added by a normal XMPP router or session manager. In addition, normal IQ result stanzas sent upon successful completion of a request (as required by XMPP Core 11 ) are not shown. 7.1 Order of Events The order of events involved in joining a room needs to be consistent so that clients can know which events to expect when. After a client sends presence to join a room, the MUC service MUST send it events in the following order: 11 RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core < 22

29 7 OCCUPANT USE CASES 1. In-room presence from other occupants 2. In-room presence from the joining entity itself (so-called self-presence ) 3. Room history (if any) 4. The room subject 5. Live messages, presence updates, new user joins, etc. 7.2 Entering a Room Groupchat 1.0 Protocol In order to participate in the discussions held in a multi-user chat room, a user MUST first become an occupant by entering the room. In the old groupchat 1.0 protocol, this was done by sending presence with no type attribute to <room@service/nick>, where room is the room ID, service is the hostname of the chat service, and nick is the user s desired nickname within the room: Listing 18: User Seeks to Enter a Room (groupchat 1.0) from = hag66@shakespeare.lit /pda id= ng91xs69 to= coven@chat. shakespeare.lit / thirdwitch /> In this example, a user with a full JID of hag66@shakespeare.lit/pda has requested to enter the room coven on the chat.shakespeare.lit chat service with a room nickname of thirdwitch. If the user does not specify a room nickname (note the bare JID on the from address in the following example), the service MUST return a <jid-malformed/> error: Listing 19: No Nickname Specified from = coven@chat. shakespeare. lit id= 273 hs51g to= hag66@shakespeare.lit /pda type = error > <error by= coven@chat. shakespeare.lit type = modify > <jid - malformed xmlns = urn:ietf:params:xml:ns:xmpp - stanzas /> </ error > </ presence > Note: The presence stanza used to join a room MUST NOT possess a type attribute, i.e., it must be available presence. For further discussion, see the Presence business rules. 23