XEP-xxxx: Multi-User Collaboration

This document describes an XMPP extension for Multi-User Collaboration.



XEP Information

Status: ProtoJEP
Type: Standards Track
Number: xxxx
Version: 0.0.1
Last Updated: 2006-10-16
Publishing Organization: Jabber Software Foundation
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, XEP-0030, XEP-0045, XEP-0128, XEP-0166
Supersedes: None
Superseded By: None
Short Name: MUCol
Wiki Page: <http://wiki.jabber.org/index.php/Multi-User Collaboration (XEP-xxxx)>

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Hugues Pisapia

Email: hpisapia@horizonwimba.com
JID: huguespisapia@im.apinc.org

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Table of Contents

1. Introduction
2. Requirements
3. Glossary
4. Roles and Media
5. Use Cases
5.1. Entity Use Cases
5.1.1. Discovering Component support for MUCol
5.1.2. Discovering User support for MUCol
5.2. Occupant Use Cases
5.2.1. Entering a room
5.2.1.1. User enters room
5.2.1.2. Service annouces current media used in the room
5.2.1.3. Presence Broadcast
5.2.1.4. Default Roles/Security
5.2.2. User requests Media Information
5.2.3. User connects to Media
5.2.4. User declines media
5.2.5. User speaks/is silent
5.2.6. Exiting a Room
5.2.7. Inviting a user in a room
5.2.8. Converting a previous discussion into a MUCol.
5.2.8.1. Converting a MUC Text room into an MUCol Room
5.2.9. Requesting Voice
5.3. Moderator Use Cases
5.3.1. Granting/Revoking a Media Voice
5.3.2. Modifying the media voice list
5.3.3. Initiating a media session
5.3.4. Terminating a Media session
5.4. Administrator Use Cases
5.5. Owner User Cases
6. Business Rules
7. Implementation Notes
8. Internationalization Considerations
9. Security Considerations
10. IANA Considerations
11. Jabber Registrar Considerations
12. XML Schema
12.1. http://jabber.org/protocol/mucol
12.2. http://jabber.org/protocol/mucol#media
12.3. http://jabber.org/protocol/mucol#admin
Notes
Revision History


1. Introduction

Multi-User Chat [1], also known as MUC, extends the XMPP protocol to enable several people to communicate in a many-to-many using text chat. However, access to broaband Internet communication allows many-to-many communication using other means that text-only chat.

This document describes a protocol, leveraging MUC, to enable many-to-many communication and collaboration including, but not limited to audio, video... These extensions are implemented using protocol elements qualified by the 'http://jabber.org/protocol/mucol' namespace (and the #media and #admin fragments on the main namespace URI).

This protocol is designed as a framework that can be used to build connectivity to/management of Collaborative Media such as whiteboard, screen sharing, document sharing, audio/video... The various protocols for such Media should be the object of separated XEPs.

This protocol DOES NOT define how the Client will connect to the Media, even though the use of Jingle [2] is recommended.

2. Requirements

Multi User Collaboration MUST support Multi-User Chat [3]

3. Glossary

Media -- a mean of real-time communication.

4. Roles and Media

Multi-User Chat [4] defines roles as the short-lived set of privileges a Room Occupants has ('voice', kick users...). MUCol defines the same Roles but relating to Media.

MUCol defines the following set of basic roles for a Media:

5. Use Cases

5.1 Entity Use Cases

5.1.1 Discovering Component support for MUCol

The [http://www.jabber.org/registrar/disco-categories.html#conference Conference] Category of Service Discovery [5] identities, does not cover the media room that could allow room Occupants to exchange/share a media while in a conference room. So MUCol should annouce itself using the 'media' type in the 'conference' category when a user queries a room using disco. The 'media' type for the 'conference' category of discovery will idenfy MUCol rooms as the 'text' type identifies standards MUC rooms.

Example 1. User Queries Chat Service for MUCol Support via Disco

<iq from='hag66@shakespeare.lit/pda'
    id='disco1'
    to='macbeth.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

The service MUST return its identity and the features it supports. It includes a 'feature' element qualified by the namespace 'http://jabber.org/prococol/mucol'. It MUST also include a 'feature' element qualified by the namespace 'http://jabber.org/protocolo/muc' for compatibility with standard MUC clients.

Example 2. Service Returns Disco Info Results

<iq from='macbeth.shakespeare.lit'
    id='disco1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='Macbeth Chat Service'
        type='media'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='http://jabber.org/protocol/mucol'/>
  </query>
</iq>

Items are handled just like in MUC.

Using Disco, a user may also require a specific information about a specific chat room for more detailed information about the room:

Example 3. User Queries for Information about a Specific Chat Room

<iq from='hag66@shakespeare.lit/pda'
    id='disco3'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

The room MUST return its identity and SHOULD return the features it supports:

Example 4. Room Returns Disco Info Results

<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco3'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='media'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='http://jabber.org/protocol/mucol'/>
    <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>
</iq>

A chatroom MAY return more detailed information in its disco#info response using Service Discovery Extensions [6], identified by inclusion of a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/muc#roominfo". Such information might include a more verbose description of the room, the current room subject, the current number of occupants in the room.

As explained in Service Discovery Extensions [7] in section 4, MUCol will add an another hidden FORM_TYPE field announcing the availability of extended information about MUCol :

Example 5. Room Returns Extended Disco Info Results

<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco3a'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='media'/>
    <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'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#roominfo</value>
      </field>
      <field var='muc#roominfo_description' label='Description'>
        <value>The place for all good witches!</value>
      </field>
      <field var='muc#roominfo_subject' label='Subject'>
        <value>Spells</value>
      </field>
      <field var='muc#roominfo_occupants' label='Number of occupants'>
        <value>3</value>
      </field>
      <field var='muc#roominfo_lang' label='Language of discussion'>
        <value>en</value>
      </field>
    </x>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/mucol#roominfo</value>
      </field>
      <field var='mucol#roominfo_media' label='IAX audio'>
        <value>audio</value>
      </field>
      <field var='mucol#roominfo_media' label='IAX video'>
        <value>video</value>
      </field>
      <field var='mucol#roominfo_media' label='White Board'>
        <value>whiteboard</value>
      </field>
      <field var='mucol#roominfo_media' label='File Store'>
        <value>file</value>
      </field>
    </x>
  </query>
</iq>

5.1.2 Discovering User support for MUCol

TODO

5.2 Occupant Use Cases

5.2.1 Entering a room

In order to participate in the discussions held in a Multi-User Collaboration room, an XMPP user MUST first become an occupant by entering the room. In the old "groupchat 1.0" protocol, this was done by sending presence 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:

  1. User sends presence to enter the room

    • If cannot enter, same behavior as MUC.

    • if he can, send media currently in use.

  2. Server broadcasts presence when user connected to the room with initial media info.

  3. Server sends media available in the room.

    • media can be one of:
      • audio

      • video

      • whiteboard

      • Document Sharing

      • Screen Sharing

      • ...

    • The 'role' attribute of the 'media' element of the user has the value "unknown" until the user actually connects to the media, which he could decline formaly by sending a 'media' element with the attribute 'role' set to the value "none".

      Note: For each type of media, we should initiate a jingle session between the client and <room@service>.

  4. User connects (or decline) media.

    It might be possible for users to decline a Media while connecting into a MUCol room. For instance, a client joins a MUCol room with an audio Media while his audio is already used. In this case, it would be unappropriate to connect to an audio Media.

  5. Server send updated Presence status

5.2.1.1 User enters room

Example 6. Jabber User Seeks to Enter a Room (Groupchat 1.0)

            
<presence from='hag66@shakespeare.lit/pda'
          to='darkcave@macbeth.shakespeare.lit/thirdwitch'/>
          
          

Example 7. Jabber User Seeks to Enter a Room (MUCol)

<presence from='hag66@shakespeare.lit/pda'
          to='darkcave@macbeth.shakespeare.lit/thirdwitch'>
   <x xmlns='http://jabber.org/protocol/muc'/>
   <x xmlns='http://jabber.org/protocol/mucol'/>
</presence>

In this later example, the client advertizes its support for MUC and MUCol for compatibility with MUC-Only servers.

5.2.1.2 Service annouces current media used in the room

In the media room, the service will inform the Jabber user of the media available in this room with an IQ set:

Example 8. Service announces available media in the room

<iq to='hag66@shakespeare.lit/' from='darkcave@macbeth.shakespeare.lit' id='media1' type='set'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' uri='iax2://darkcave@ast1.shakespeare.lit/123456'/>
    <media type='whiteboard' uri='xvnc://darkcave@reflector1.shakespeare.lit/somewhiteboardid'/>
  </x>
</iq>

The room could also be streaming a media to users, just like in a movie threater:

Example 9. Server announces a movie

<iq to='hag66@shakespeare.lit/' from='darkcave@macbeth.shakespeare.lit' id='media1' type='set'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='video' uri='rtsp://darkcave@real1.shakespeare.lit/starwars'/>
  </x>
</iq>

Then the user ack's reception of media. Though this does not give the service any indication on the Client will connect or not to the Media.

Example 10. Jabber user acknowledges the room information received

            
<iq to='hag66@shakespeare.lit/' 
    from='darkcave@macbeth.shakespeare.lit' id='media1' type='result'/>

Note : We should be conformant with Jingle Audio Content Description Format [8] or Jingle Video Content Description Format [9] and the various Jingle Transport methods like Jingle IAX Transport Method [10].

5.2.1.3 Presence Broadcast

If the service is able to add the user into the room, it must send presence from all existing occupant's room JIDs to the new occupant:

Example 11. Service Sends Presence from Existing Occupants to New Occupant

            
<presence
    from='darkcave@macbeth.shakespeare.lit/firstwitch'
    to='hag66@shakespeare.lit/pda'>
  <x mxlns='http://jabber.org/protocool.muc'>
    <item affiliation='owner' role='moderator'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='moderator'/>
    <media type='whiteboard' role='moderator'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/secondwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin' role='moderator'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='moderator'/>
    <media type='whiteboard' role='moderator'/>
  </x>
</presence>

In this example, the user from the previous example has entered the room, by which time two other people had already entered the room: a user with a room nickname of "firstwitch" (who is a room owner) and a user with a room nickname of "secondwitch" (who is a room admin).

In a later example, 'secondwitch' could be a 'visitor' with no particuliar affiliation ('None'), but who can talk, but not update the whiteboard.

Example 12. Service Sends Presence from Existing Occupants to New Occupant (2)

<presence
    from='darkcave@macbeth.shakespeare.lit/firstwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='moderator'/>
    <media type='whiteboard' role='moderator'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/secondwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant'/>
    <media type='whiteboard' role='visitor'/>
  </x>
</presence>

The service MUST also send presence from the new occupant's room JID to the full JIDs of all the occupants (including the new occupant):

Example 13. Service Sends New Occupant s Presence to All Occupants

            
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='unknown'/>
    <media type='whiteboard' role='unknown'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='unknown'/>
    <media type='whiteboard' role='unknown'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='unknown'/>
    <media type='whiteboard' role='unknown'/>
  </x>
</presence>

In this example, initial room presence is being sent from the new occupant (thirdwitch) to all occupants, including the new occupant.

The order of the presence stanzas sent to the new occupant is important. The service MUST first send the complete list of the existing occupants to the new occupant and only then send the new occupant's own presence to the new occupant. This helps the client know when it has received the complete "room roster".

5.2.1.4 Default Roles/Security

The same default roles as 'item' elements applies for 'media' elements when a user with a particular affiliation enters a room. In particular, 'outcast' affiliation should prevent users to connect to any media available in a room since they are not allowed to enter the room.

Also, the user should authenticate first to the room (if required) before being able to connect to any Media associated to the room.

When a user connect to a room, but is not connected to a Media, the 'role' attribute of the 'media' element is set by default to "unknown" until the client connects to the media, or decline to connect the Media. In this case, a 'media' element with the 'role' attribute set to the value of "none" is broadcasted to all occupants, and the User Interface should reflect this status to users.

Note : It is not described here how a media checks if a user is authorized or not to connect. this is left to the implementation ;)

5.2.2 User requests Media Information

Participants might require the media information in order to join a group call already running in the room. To do so, they have to send to the room an IQ-set, with the role they request. The server will then return the media uri in an IQ result, or an error.

Example 14. Participant requests media information

<iq from='crone1@shakespeare.lit/desktop'
    id='mediareq1'
    to='darkcave@macbeth.shakespeare.lit'
    type='set'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant'/>
  </x>
</iq>

In case the server accepts, it returns the media info by the mean of an IQ-result containing an 'x' element qualified by the namespace 'http://jabber.org/protocol/mucol#media'. This element contains a child 'media' element with the attribute type whose value is set to the kind of Media requested, and the attribute 'uri' whose value is set to to a specific value describing the mean to use to connect to the Media this element refers to, for this User, in this MUCol room. [11]

Example 15. Server informs new participant about his new Media

<iq to='crone1@shakespeare.lit/desktop' 
    from='darkcave@macbeth.shakespeare.lit' 
    id='media1' type='result'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' uri='iax2://darkcave@ast1.shakespeare.lit/123456'/>
  </x>
</iq>

The server might want to ask an admin to check if this user can have the media-role of "participant" instead of "none", and eventually deny access.

In case the server denies access it returns an IQ error stanza as shown below"

Example 16. Server denies acces to new participant

<iq type='error' to='crone1@shakespeare.lit/desktop' from='darkcave@macbeth.shakespeare.lit' id='media1'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant'/>
  </x>
  <error code="503" type="cancel">
    <service-unavailable xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
  </error>
</iq>

When the user has received his Media information he then connect to the media as described below.

5.2.3 User connects to Media

When the user connects to a Media announced in a room, the service should send updated Presence information with the updated Media items. In the examples below, the user (or in fact the IM client) connects to the whiteboard Media.

Example 17. Servers sends broadcasts extended Presence when user connects to Media

          
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'/>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'/>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'/>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>

5.2.4 User declines media

It might be possible for users to decline a Media while connecting into a MUCol room. For instance, a student joins a room while attending a lecture. In this case, it would be unappropriate to connect to an audio Media. In this case, the user will send a Presence stanza to the server, that will broadcast the decline to all occupants of the room.

Example 18. User declines a Media when entering a room

<presence
   from='hag66@shakespeare.lit/pda'
   to='darkcave@macbeth.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='whiteboard' role='visitor'/>
    <media type='audio' role='none'>
      <decline>busy</decline>
    </media>
  </x>
</presence>

The server should then clean up the resources involved to connect to the media and broadcast this info to occupants of the room.

Example 19. Servers sends broadcasts Presence when user declines Media

          
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'>
      <decline>busy</decline>
    </media>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'>
      <decline>busy</decline>
    </media>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='none'>
      <decline>busy</decline>
    </media>
    <media type='whiteboard' role='participant'/>
  </x>
</presence>

5.2.5 User speaks/is silent

At some point, a user will be a source of Media (e.g Romeo speaks, and his client sends audio to the room). In a room, it is often usefull to know who is speaking, or acting as a source for a Media. For instance, the voice might be distorted, or you do not even recognize the voice of a person you never heard before.

When a user is speaking, or is emitting a media, the server SHOULD immediatelly sends a updated Presence stanza, updating the media status of the person. the 'media' element will therefore contain the attribute 'emit' with the value "true" or "false". When the attribute is not included, it must be considered as having the value of "false".

Example 20. User emits audio

<presence
     from='darkcave@macbeth.shakespeare.lit/thirdwitch'
     to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant' emit='true'/>
  </x>
</presence>
<presence
     from='darkcave@macbeth.shakespeare.lit/thirdwitch'
     to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant' emit='true'/>
  </x>
</presence>
<presence
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant' emit='true'/>
  </x>
</presence>

5.2.6 Exiting a Room

When a user exists a room, the server should check the connection is closed to every Media this user was connected to before broadcasting the Unavailable Presence stanzas to the remaining occupants, eventually sending a 'media' element with the attribute 'role' set to the value of "none" before the user actually leaves the room.

The presence stanzas do not contain 'media' elements as it is irrelevant.

5.2.7 Inviting a user in a room

Just like in MUC, an inviter should send a Message stanza with an 'invite' element to the room. The service then forwards the invitation to the invitee on behalf of the inviter.

; Note : Ability to invite people in member-only rooms is discussed in the Multi-User Chat [12].

A MUC client MUST send XML of the following form to the <room@service> itself (the reason is OPTIONAL and the message MUST NOT possess a 'type' attribute; the service MAY ignore or reject invites that possess a 'type' attribute):

Example 21. Occupant Sends an Invitation by Way of Room (Multi-User Chat)

          
<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'>
      <reason>
        Hey Hecate, this is the place for all good witches!
      </reason>
    </invite>
  </x>
</message>

The <room@service> itself MUST then add a 'from' address to the 'invite' element whose value is the bare JID (or, optionally, the room JID) of the invitor and send the invitation to the invitee captured in the 'to' address (the service SHOULD include a message body explaining the invitation or containing the reason, for the sake of older clients; in addition, the room SHOULD add the password if the room is password-protected) and MAY include the old jabber:x:conference extension as well for backwards-compatibility:

Example 22. Room Sends Invitation to Invitee on Behalf of Invitor

          
<message
    from='darkcave@macbeth.shakespeare.lit'
    to='hecate@shakespeare.lit'>
  <body>You have been invited to darkcave@macbeth by crone1@shakespeare.lit.</body>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit'>
      <reason>
        Hey Hecate, this is the place for all good witches!
      </reason>
    </invite>
    <password>cauldron</password>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' uri='iax2://darkcave@ast1.shakespeare.lit/123456'/>
    <media type='whiteboard' uri='xvnc://darkcave@reflector1.shakespeare.lit/someidentifier'/>
  </x>
  <x jid='darkcave@macbeth.shakespeare.lit' xmlns='jabber:x:conference'>
    Hey Hecate, this is the place for all good witches!
  </x>
</message>

The invitee may formally decline the invitation, as opposed to ignore it.

Example 23. Invitee Declines Invitation

<message
    from='hecate@shakespeare.lit/broom'
    to='darkcave@macbeth.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <decline to='crone1@shakespeare.lit'>
      <reason>
        Sorry, I'm too busy right now.
      </reason>
    </decline>
  </x>
</message>

Example 24. Room Informs Invitor that Invitation Was Declined

<message
    from='darkcave@macbeth.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <decline from='hecate@shakespeare.lit'>
      <reason>
        Sorry, I'm too busy right now.
      </reason>
    </decline>
  </x>
</message>

See XEP-0045 for more details about invitations

5.2.8 Converting a previous discussion into a MUCol.

Sometime, it is desirable to convert a one-to-one discussion, or a text-based conference into a media multi-uer conference. The next sections show the process flow for such a convertion.

Table 1: Convertion from existing 1-to-1, or text-based MUC discussion to MUCol

-> One-to-One Multi-User
Text This convertion from a text, one-to-one into a conference, is explained in the Multi-User Chat [13]. This specification should be used in order to create a MUCol conference In case users are using Multi-User Chat [14] to communicate (that this protocol should follow), a user with 'moderator' role can open a media. If not possible, the invite method described below should be used in order to create a new room and then invite all occupants of the previous room to the newly created MUCol room.
Media In order to move into a media-based room, users should first shutdown their current media session, and then proceed to the room following the standard invite method shown below. N/A

5.2.8.1 Converting a MUC Text room into an MUCol Room

Users connected to a MUC text-room might want to enable a Media. However, a User sith status 'Moderator' is not always available to initiate a Media. So it if often usefull to be able to transfer Users in a MUCol room where one is 'Moderator'. The following example shows the path to proceed.

Three users are in in a room:

Example 25. A text MUC chat

<message
    from='hag66@shakespeare.lit/pda'
    to='textcave@shakespeare.lit'
    type='groupchat'>
  <body>Thrice the brinded cat hath mew'd.</body>
</message>

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='textcave@shakespeare.lit'
    type='groupchat'>
  <body>Thrice and once the hedge-pig whined.</body>
</message>

<message
    from='crone1@shakespeare.lit/desktop'
    to='textcave@shakespeare.lit'
    type='groupchat'>
  <body>That ain't gonna work, we should speak it.</body>
</message></nowiki>

Now, the third person decides to move people into another room, so her client does the following:

  1. Create a new MUCol room, with an Audio Media flag
  2. Optionnally sends history to the room
  3. Send an invitation to other people in the MUCol room, including a 'continue' element.

Example 26. Continuing the Discussion I: User Creates Room

<presence
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit/firstwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
  <x xmlns='http://jabber.org/protocol/mucol'>
    <media type='audio'/>
  </x>
</presence>
.
.
The service sends an IQ set with an Audio Media information. 
The user ack's and then connects.
.
.
<presence
    from='darkcave@macbeth.shakespeare.lit/firstwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='moderator'/>
  </x>
</presence>

Example 27. Continuing the Discussion II: Owner Sends History to Room

            
<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <body>Thrice the brinded cat hath mew'd.</body>
  <x xmlns='jabber:x:delay'
     from='hag66@shakespeare.lit/pda'
     stamp='20040929T01:54:37'/>
</message>

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <body>Thrice and once the hedge-pig whined.</body>
  <x xmlns='jabber:x:delay'
     from='wiccarocks@shakespeare.lit/laptop'
     stamp='20040929T01:55:21'/>
</message>

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <body> That ain't gonna work, we should speak it.</body>
  <x xmlns='jabber:x:delay'
     from='crone1@shakespeare.lit/desktop'
     stamp='20040929T01:56:01'/>
</message>

This example uses Delayed delivery as explained in Multi-User Chat [15].

Example 28. Continuing the Discussion III: Owner Sends Invitations, Including Continue Flag

            
<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@macbeth.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='wiccarocks@shakespeare.lit/laptop'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue/>
    </invite>
    <invite to='hag66@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue/>
    </invite>
  </x>
</message>

Example 29. Invitations Delivered

<message
    from='darkcave@macbeth.shakespeare.lit'>
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue/>
    </invite>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio'/>
  </x>
</message>

<message
    from='darkcave@macbeth.shakespeare.lit'>
    to='hag66@shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue/>
    </invite>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio'/>
  </x>
</message>

When the client being used by <wiccarocks@shakespeare.lit/laptop> and <hag66@shakespeare.lit/pda> receives the invitation, it SHOULD auto-join the room or prompt the user whether to join (subject to user preferences) and then seamlessly convert the existing chat window into a MUCol conferencing window.

5.2.9 Requesting Voice

TODO, like in MUC

5.3 Moderator Use Cases

Multi-User Chat [16] covers the following use cases that moderator might be granted the privileges to:

These features are implemented as IQ request/response using a child element qualified with the 'http://jabber.org/protocol/mucol#admin' namespace.

The addition of media in a room involves the following new use cases:

  1. granting media voice to participants
  2. revoking media voice to participants
  3. Initiating a Media
  4. terminating a Media

5.3.1 Granting/Revoking a Media Voice

The grant/revoke process is similar to Granting/Revoking "text" voice in MUC:

  1. moderator sends IQ set with the new role of the participant for a particular Media available in the room.
  2. service informs moderator of success/failure
  3. service sends Presence notification to all occupants

Example 30. Moderator Grants Voice to a Visitor

<iq from='crone1@shakespeare.lit/desktop'
    id='voice1'
    to='darkcave@macbeth.shakespeare.lit'
    type='set'>
  <x xmlns='http://jabber.org/protocol/mucol#admin'>
    <media type='audio' role='participant' nick='thirdwitch'>
      <reason>A worthy witch indeed!</reason>
    </media>
  </x>
</iq>

The service MUST then inform the moderator of success or failure. In case of failure, the service MUST indicate the reason.

Example 31. Service Informs Moderator of Success

<iq from='darkcave@macbeth.shakespeare.lit'
    id='voice1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>

Example 32. Service Informs Moderator of Failure

<iq from='darkcave@macbeth.shakespeare.lit'
    id='voice1'
    to='crone1@shakespeare.lit/desktop'
    type='error'>
  <error code="503" type="cancel">
    <service-unavailable xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
  </error>
</iq>

The service MUST then send updated presence from this individual's <room@service/nick> to all occupants, indicating the addition of voice privileges by including an 'x' element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an 'item' child with the 'role' attribute set to a value of "participant" and an 'x' element qualified by the 'http://jabber.org/protocol/mucol#media' namespace and containing a 'media' child with the 'role' attribute set to a value of "participant".

Example 33. Service Sends Notice of Voice to All Occupants

<presence
   from='darkcave@macbeth.shakespeare.lit/thirdwitch'
   to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          nick='thirdwitch'
          role='participant'/>
  </x>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media nick='thirdwitch'
          role='participant'
          type='audio'>
      <reason>A worthy witch indeed!</reason>
    </media>
  </x>
</presence>
.
.
.

5.3.2 Modifying the media voice list

The ability to update the Voice list follows the same model as explained in MUC, by updating for each Media the role attribute:

  1. moderator queries list of participants
  2. moderator sends 'delta' (i.e. only modifications) to the service
  3. service sends modifications to all occupants of the room

5.3.3 Initiating a media session

A moderator will initiate a Media by updating his own ''media-voice'' by the mean of an IQ set as described above. The number of Media users will then move from 0 to 1. A 'reason' element is optional.

Example 34. Moderator Initiates Media-Voice to initiate Media

<iq from='crone1@shakespeare.lit/desktop'
    id='initvoice1'
    to='darkcave@macbeth.shakespeare.lit'
    type='set'>
  <x xmlns='http://jabber.org/protocol/mucol#admin'>
    <media type='audio' role='participant' nick='firstwitch'>
      <reason>Let's spell those curses !</reason>
    </media>
  </x>
</iq>

The service MUST then inform the moderator of success or failure:

Example 35. Service Informs Moderator of Success

<iq from='darkcave@macbeth.shakespeare.lit'
    id='initvoice1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant' uri='iax2://darkcave@ast1.shakespeare.lit/123456'/>
  </x>
</iq>

Example 36. Service Informs Moderator of Failure

<iq from='darkcave@macbeth.shakespeare.lit'
    id='initvoice1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <x xmlns='http://jabber.org/protocol/mucol#media'>
    <media type='audio' role='participant'/>
  </x>
  <error code="503" type="cancel">
    <service-unavailable xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
  </error>
</iq>

Upon successful completion, the server will inform all room occupants of the creation of the media and invite them to connect with an IQ-set. It performs the same way as if users had just joined the room:

Example 37. Server informs room occupants about the availability of the new Media

<iq to='wiccarocks@shakespeare.lit/laptop' from='darkcave@macbeth.shakespeare.lit' id='media1' type='set'>
  <x xmlns='http://horizonwimba.com/protocol/mmuc#media'>
    <media type='audio' role='participant' uri='iax2://darkcave@ast1.shakespeare.lit/654321'/>
  </x>
</iq>
<iq to='hag66@shakespeare.lit/pda' from='darkcave@macbeth.shakespeare.lit' id='media1' type='set'>
  <x xmlns='http://horizonwimba.com/protocol/mmuc#media'>
    <media type='audio' role='participant' uri='iax2://darkcave@ast1.shakespeare.lit/234567'/>
  </x>
</iq>

At the same time, it will send updated Presence exended information, eventually with a the value the 'role' attribute of the 'media' element set to the value of "unknown". Users can then decide to follow-up and join the call using the 'uri' information, or formally decline the media and set his media role to "none".

5.3.4 Terminating a Media session

TODO

5.4 Administrator Use Cases

5.5 Owner User Cases

6. Business Rules

OPTIONAL.

7. Implementation Notes

OPTIONAL.

8. Internationalization Considerations

OPTIONAL.

9. Security Considerations

REQUIRED.

10. IANA Considerations

REQUIRED.

11. Jabber Registrar Considerations

REQUIRED.

12. XML Schema

12.1 http://jabber.org/protocol/mucol

    
      

12.2 http://jabber.org/protocol/mucol#media

<?xml version='1.0' encoding='UTF-8'?>

 <xs:schema
     xmlns:xs='http://www.w3.org/2001/XMLSchema'
     targetNamespace='http://jabber.org/protocol/mucol#media'
     xmlns='http://jebber.org/protocol/mucol#media'
     elementFormDefault='qualified'>

   <xs:annotation>
     <xs:documentation>
       The protocol documented by this schema is defined in
       Multi-User Collaboration in XEP XXXX:
        http://xmpp.org/extensions//xep-XXXX.html
     </xs:documentation>
   </xs:annotation>

   <xs:element name='x'>
     <xs:complexType>
       <xs:choice minOccurs='0' maxOccurs='unbounded'>
         <xs:element ref='media' minOccurs='0' maxOccurs='unbounded'/>
       </xs:choice>
     </xs:complexType>
   </xs:element>

   <xs:element name='media'>
     <xs:complexType>
       <xs:choice>
         <xs:element ref='reason' minOccur='0' maxOccurs='1'/>
         <xs:element ref='decline' minOccur='0' maxOccurs='1'/>
       </xs:choice>
      <xs:attribute name='type' type='xs:string' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='audio'/>
            <xs:enumeration value='video'/>
            <xs:enumeration value='whiteboard'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='emit' type='xs:string' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='true'/>
            <xs:enumeration value='false'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='nick' type='xs:string' use='optional'/>
      <xs:attribute name='role' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='moderator'/>
            <xs:enumeration value='none'/>
            <xs:enumeration value='participant'/>
            <xs:enumeration value='unknown'/>
            <xs:enumeration value='visitor'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
     </xs:complexType>
   </xs:element>

   <xs:element name='reason' type='xs:string'/>

   <xs:element name='decline'>
     <xs:complexType>
       <xs:sequence>
         <xs:element ref='reason' minOccurs='0'/>
       </xs:sequence>
       <xs:attribute name='from' type='xs:string' use='optional'/>
       <xs:attribute name='to' type='xs:string' use='optional'/>
     </xs:complexType>
   </xs:element>
 </schema>
 
      

12.3 http://jabber.org/protocol/mucol#admin

    
      


Notes

1. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

2. XEP-0166: Jingle <http://www.xmpp.org/extensions/xep-0166.html>.

3. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

4. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

5. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.

6. XEP-0128: Service Discovery Extensions <http://www.xmpp.org/extensions/xep-0128.html>.

7. XEP-0128: Service Discovery Extensions <http://www.xmpp.org/extensions/xep-0128.html>.

8. XEP-0167: Jingle Audio Content Description Format <http://www.xmpp.org/extensions/xep-0167.html>.

9. XEP-0180: Jingle Video Content Description Format <http://www.xmpp.org/extensions/xep-0180.html>.

10. XEP-0179: Jingle IAX Transport Method <http://www.xmpp.org/extensions/xep-0179.html>.

11. The 'uri' attribute is what we have currently deployed, according to the fact that we developped this protocol while Jingle was not yet a draft. Establishing a Jingle session between the Client and the JID of the Room, handled by the server, seems a reasonable alternative.

12. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

13. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

14. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

15. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.

16. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.


Revision History

Version 0.0.1 (2006-10-16)

First draft.

(hp)


END