source: wokkel/muc.py @ 130:45c3ce4fe4eb

# -*- test-case-name: wokkel.test.test_muc -*-
#
# Copyright (c) 2003-2009 Ralph Meijer
# See LICENSE for details.

"""
XMPP Multi-User Chat protocol.

This protocol is specified in
U{XEP-0045<http://www.xmpp.org/extensions/xep-0045.html>}.
"""
import datetime

from zope.interface import implements

from twisted.internet import defer, reactor
from twisted.words.protocols.jabber import jid, error, xmlstream
from twisted.words.xish import domish

from wokkel import data_form, xmppim
from wokkel.subprotocols import XMPPHandler
from wokkel.iwokkel import IMUCClient

# Multi User Chat namespaces
NS_MUC = 'http://jabber.org/protocol/muc'
NS_MUC_USER = NS_MUC + '#user'
NS_MUC_ADMIN = NS_MUC + '#admin'
NS_MUC_OWNER = NS_MUC + '#owner'
NS_MUC_ROOMINFO = NS_MUC + '#roominfo'
NS_MUC_CONFIG = NS_MUC + '#roomconfig'
NS_MUC_REQUEST = NS_MUC + '#request'
NS_MUC_REGISTER = NS_MUC + '#register'

NS_DELAY = 'urn:xmpp:delay'
NS_JABBER_DELAY = 'jabber:x:delay'

NS_REQUEST = 'jabber:iq:register'

# Iq get and set XPath queries
IQ = '/iq'
IQ_GET = IQ+'[@type="get"]'
IQ_SET = IQ+'[@type="set"]'

IQ_RESULT = IQ+'[@type="result"]'
IQ_ERROR = IQ+'[@type="error"]'

IQ_QUERY = IQ+'/query'
IQ_GET_QUERY = IQ_GET + '/query'
IQ_SET_QUERY = IQ_SET + '/query'

IQ_COMMAND = IQ+'/command'

MUC_ADMIN = IQ_QUERY+'[@xmlns="' + NS_MUC_ADMIN + '"]'
MUC_OWNER = IQ_QUERY+'[@xmlns="' + NS_MUC_OWNER + '"]'

MUC_AO = MUC_ADMIN + '|' + MUC_OWNER


MESSAGE = '/message'
PRESENCE = '/presence'

CHAT_BODY = MESSAGE +'[@type="chat"]/body'
CHAT = MESSAGE +'[@type="chat"]'

GROUPCHAT = MESSAGE +'[@type="groupchat"]/body'
SUBJECT = MESSAGE +'[@type="groupchat"]/subject'
MESSAGE_ERROR = MESSAGE +'[@type="error"]'

STATUS_CODES = { # see http://www.xmpp.org/extensions/xep-0045.html#registrar-statuscodes
    100:
        {'name':'fulljid',
         'stanza':'presence',

         },
    201:
        {'name':'created',
         'stanza': 'presence',
         'context':'Entering a room',
         'purpose':'Inform user that a new room has been created'
         },
}

STATUS_CODE_CREATED = 201

DEFER_TIMEOUT = 30 # basic timeout is 30 seconds

class JidMalformed(Exception):
    """
    A jid malformed error from the server.


    """
    condition = 'modify'
    mucCondition = 'jid-malformed'



class NotAuthorized(Exception):
    """
    """
    condition = 'auth'
    mucCondition = 'not-authorized'



class RegistrationRequired(Exception):
    """
    """
    condition = 'auth'
    mucCondition = 'registration-required'



class Forbidden(Exception):
    """
    """
    condition = 'auth'
    mucCondition = 'forbidden'



class Conflict(Exception):
    """
    """
    condition = 'cancel'
    mucCondition = 'conflict'



class NotFound(Exception):
    """
    """
    condition = 'cancel'
    mucCondition = 'not-found'



class ServiceUnavailable(Exception):
    """
    """
    condition = 'wait'
    mucCondition = 'service-unavailable'



MUC_EXCEPTIONS = {
    'jid-malformed': JidMalformed,
    'forbidden': Forbidden,
    'not-authorized': NotAuthorized,
    'exception': Exception,
    'conflict': Conflict,
    'service-unavailable': ServiceUnavailable,
    'not-found': NotFound,
    }



class MUCError(error.StanzaError):
    """
    Exception with muc specific condition.
    """
    def __init__(self, condition, mucCondition, type='error', feature=None, text=None):
        appCondition = domish.Element((NS_MUC, mucCondition))
        if feature:
            appCondition['feature'] = feature
        error.StanzaError.__init__(self, condition,
                                         type=type,
                                         text=text,
                                         appCondition=appCondition)



class BadRequest(MUCError):
    """
    Bad request stanza error.
    """
    def __init__(self, mucCondition=None, text=None):
        MUCError.__init__(self, 'bad-request', mucCondition, text)



class Unsupported(MUCError):
    def __init__(self, feature, text=None):
        MUCError.__init__(self, 'feature-not-implemented',
                          'unsupported',
                          feature,
                          text)



class ConfigureRequest(xmlstream.IQ):
    """
    Configure MUC room request.

    http://xmpp.org/extensions/xep-0045.html#roomconfig

    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    @type method: C{str}
    """

    def __init__(self, xs, method='get', fields=[]):
        xmlstream.IQ.__init__(self, xs, method)
        q = self.addElement((NS_MUC_OWNER, 'query'))
        if method == 'set':
            # build data form
            form = data_form.Form('submit', formNamespace=NS_MUC_CONFIG)
            q.addChild(form.toElement())

            for f in fields:
                # create a field
                form.addField(f)



class RegisterRequest(xmlstream.IQ):
    """
    Register room request.

    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    @type method: C{str}

    """

    def __init__(self, xs, method='get', fields=[]):
        xmlstream.IQ.__init__(self, xs, method)
        q = self.addElement((NS_REQUEST, 'query'))
        if method == 'set':
            # build data form
            form_type = 'submit'
            form = data_form.Form(form_type, formNamespace=NS_MUC_REGISTER)
            q.addChild(form.toElement())

            for f in fields:
                # create a field
                form.addField(f)



class AdminRequest(xmlstream.IQ):
    """
    A basic admin iq request

    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    @type method: C{str}

    """

    def __init__(self, xs, method='get'):
        xmlstream.IQ.__init__(self, xs, method)
        q = self.addElement((NS_MUC_ADMIN, 'query'))



class OwnerRequest(xmlstream.IQ):
    """
    A basic owner iq request

    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    @type method: C{str}

    """

    def __init__(self, xs, method='get'):
        xmlstream.IQ.__init__(self, xs, method)
        q = self.addElement((NS_MUC_OWNER, 'query'))



class AffiliationRequest(AdminRequest):
    """
    Register room request.

    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    @type method: C{str}

    @ivar affiliation: The affiliation type to send to room.
    @type affiliation: C{str}

    """

    def __init__(self, xs, method='get', affiliation='none', a_jid=None, reason=None, nick=None):
        AdminRequest.__init__(self, xs, method)

        self.affiliation = affiliation
        if a_jid is not None or nick is not None:
            i = self.query.addElement('item')
            i['affiliation'] = affiliation

        if a_jid:
            i['jid'] = a_jid.full()

        if nick:
            i['nick'] = nick

        if reason:
            i.addElement('reason', None, reason)


    def items(self, jid_list=None):
        """
        Set or Get the items list for this affiliation request.
        """
        if jid_list:
            for j in jid_list:
                i = self.query.addElement('item')
                i['affiliation'] = self.affiliation
                if isinstance(j, jid.JID):
                    i['jid'] = j.full()
                else:
                    i['nick'] = j

        return self.query.elements()



class RoleRequest(AdminRequest):
    def __init__(self, xs, method='get', role='none', a_jid=None, reason=None, nick=None):
        AdminRequest.__init__(self, xs, method)
        i = self.query.addElement('item')

        i['role'] = role
        if a_jid:
            i['jid'] = a_jid.full()
        if nick:
            i['nick'] = nick

        if reason:
            i.addElement('reason', None, reason)



class GroupChat(domish.Element):
    """
        A message stanza of type groupchat. Used to send a message to a MUC room that will be
    broadcasted to people in the room.

    """
    def __init__(self, to, body=None, subject=None, frm=None):
        """
        """
        domish.Element.__init__(self, (None, 'message'))
        self['type'] = 'groupchat'
        if isinstance(to, jid.JID):
            self['to'] = to.userhost()
        else:
            self['to'] = to
        if frm:
            self['from'] = frm
        if body:
            self.addElement('body',None, body)
        if subject:
            self.addElement('subject',None, subject)



class PrivateChat(domish.Element):
    """
        A chat message.
    """
    def __init__(self, to, body=None, frm=None):
        """
        Initialize the L{PrivateChat}

        @param to: The xmpp entity you are sending this chat to.
        @type  to: L{unicode} or L{jid.JID}

        @param body: The message you are sending.
        @type  body: L{unicode}

        @param frm: The entity that is sending the message.
        @param frm: L{unicode}

        """
        domish.Element.__init__(self, (None, 'message'))
        self['type'] = 'chat'
        if isinstance(to, jid.JID):
            self['to'] = to.userhost()
        else:
            self['to'] = to
        if frm:
            self['from'] = frm
        if body:
            self.addElement('body',None, body)



class InviteMessage(domish.Element):
    def __init__(self, bareRoomJID, invitee, reason=None):
        domish.Element.__init__(self, (None, 'message'))
        self['to'] = unicode(bareRoomJID)
        x = self.addElement('x', NS_MUC_USER)
        invite = x.addElement('invite')
        invite['to'] = invitee
        if reason:
            invite.addElement('reason', None, reason)



class HistoryMessage(GroupChat):
    """
        A history message for MUC groupchat history.
    """
    def __init__(self, to, stamp, body=None, subject=None, frm=None, h_frm=None):
        GroupChat.__init__(self, to, body=body, subject=subject, frm=frm)
        d = self.addElement('delay', NS_DELAY)
        d['stamp'] = stamp
        if h_frm:
            d['from'] = h_frm



class HistoryOptions(object):
    """
        A history configuration object.

    @ivar maxchars: Limit the total number of characters in the history to "X"
                    (where the character count is the characters of the complete XML stanzas, not only their XML character data).
    @type maxchars: L{int}

    @ivar  maxstanzas:  Limit the total number of messages in the history to "X".
    @type mazstanzas: L{int}

    @ivar  seconds: Send only the messages received in the last "X" seconds.
    @type seconds: L{int}

    @ivar  since: Send only the messages received since the datetime specified (which MUST conform to the DateTime profile specified in XMPP Date and Time Profiles [14]).
    @type since: L{datetime.datetime}

    """
    attributes = ['maxchars', 'maxstanzas', 'seconds', 'since']

    def __init__(self, maxchars=None, maxstanzas=None, seconds=None, since=None):
        self.maxchars = maxchars
        self.maxstanzas = maxstanzas
        self.seconds = seconds
        self.since = since


    def toElement(self):
        """
        Returns a L{domish.Element} representing the xml for the history options.
        """
        h = domish.Element((None, 'history'))
        for key in self.attributes:
            a = getattr(self, key, None)
            if a is not None:
                if key == 'since':
                    h[key] = a.strftime('%Y%m%dT%H:%M:%S')
                else:
                    h[key] = str(a)

        return h



class User(object):
    """
    A user/entity in a multi-user chat room.
    """

    def __init__(self, nick, entity=None):
        self.nick = nick
        self.entity = entity
        self.affiliation = 'none'
        self.role = 'none'

        self.status = None
        self.show = None



class Room(object):
    """
    A Multi User Chat Room. An in memory object representing a MUC room.
    """


    def __init__(self, roomIdentifier, service, nick, state=None):
        """
        Initialize the room.

        @ivar roomIdentifier: The Room ID of the MUC room.
        @type roomIdentifier: L{unicode}

        @ivar service: The server where the MUC room is located.
        @type service: L{unicode}

        @ivar nick: The nick name for the client in this room.
        @type nick: L{unicode}

        @ivar state: The status code of the room.
        @type state: L{int}

        @ivar roomJID: The JID of the occupant in the room. Generated from roomIdentifier, service, and nick.
        @type roomJID: L{jid.JID}

        """
        self.state = state
        self.roomIdentifier = roomIdentifier
        self.service = service
        self.nick = nick
        self.status = 0

        self.roomJID = self.refreshRoomJID()

        self.roster = {}


    def refreshRoomJID(self):
        """
        Refreshes the Room JID.

        This method should be called whenever roomIdentifier, service, or nick
        change.
        """
        self.roomJID = jid.internJID(u"%s@%s/%s" % (self.roomIdentifier,
                                                    self.service,
                                                    self.nick))
        return self.roomJID


    def addUser(self, user):
        """
        Add a user to the room roster.

        @param user: The user object that is being added to the room.
        @type  user: L{User}

        """
        self.roster[user.nick.lower()] = user


    def inRoster(self, user):
        """
        Check if a user is in the MUC room.

        @param user: The user object to check.
        @type  user: L{User}

        """

        return self.roster.has_key(user.nick.lower())


    def getUser(self, nick):
        """
        Get a user from the room's roster.

        @param nick: The nick for the user in the MUC room.
        @type  nick: L{unicode}

        """
        return self.roster.get(nick.lower())


    def removeUser(self, user):
        """
        Remove a user from the MUC room's roster.

        @param user: The user object to check.
        @type  user: L{User}

        """
        if self.inRoster(user):
            del self.roster[user.nick.lower()]



class BasicPresence(xmppim.AvailablePresence):
    """
    This behaves like an object providing L{domish.IElement}.

    """

    def __init__(self, to=None, show=None, statuses=None):
        xmppim.AvailablePresence.__init__(self, to=to, show=show, statuses=statuses)
        # add muc elements
        x = self.addElement('x', NS_MUC)



class UserPresence(xmppim.Presence):
    """
    This behaves like an object providing L{domish.IElement}.

    """

    def __init__(self, to=None, type=None, frm=None, affiliation=None, role=None):
        xmppim.Presence.__init__(self, to, type)
        if frm:
            self['from'] = frm
        # add muc elements
        x = self.addElement('x', NS_MUC_USER)
        if affiliation:
            x['affiliation'] = affiliation
        if role:
            x['role'] = role



class UnavailableUserPresence(xmppim.UnavailablePresence):
    """
    This behaves like an object providing L{domish.IElement}.

    """

    def __init__(self, to=None, type=None, frm=None, affiliation=None, role=None):
        xmppim.UnavailablePresence.__init__(self, to, type)
        if frm:
            self['from'] = frm
        # add muc elements
        x = self.addElement('x', NS_MUC_USER)
        if affiliation:
            x['affiliation'] = affiliation
        if role:
            x['role'] = role



class PasswordPresence(BasicPresence):
    """
        This behaves like an object providing L{domish.IElement}.
    """
    def __init__(self, to, password):
        BasicPresence.__init__(self, to)

        self.x.addElement('password', None, password)



class MessageVoice(GroupChat):
    """
        This behaves like an object providing L{domish.IElement}.
    """
    def __init__(self, to=None, frm=None):
        GroupChat.__init__(self, to=to, frm=frm)
        # build data form
        form = data_form.Form('submit', formNamespace=NS_MUC_REQUEST)
        form.addField(data_form.Field(var='muc#role',
                                      value='participant',
                                      label='Requested role'))
        self.addChild(form.toElement())



class PresenceError(xmppim.Presence):
    """
    This behaves like an object providing L{domish.IElement}.

    """

    def __init__(self, error, to=None, frm=None):
        xmppim.Presence.__init__(self, to, type='error')
        if frm:
            self['from'] = frm
        # add muc elements
        x = self.addElement('x', NS_MUC)

        # add error
        e = error.getElement()
        self.addChild(e)



class MUCClient(XMPPHandler):
    """
    Multi-User Chat client protocol.

    This is a subclass of L{XMPPHandler} and implements L{IMUCCLient}.

    @ivar _rooms: Collection of occupied rooms, keyed by the bare JID of the
                  room. Note that a particular entity can only join a room once
                  at a time.
    @type _rooms: C{dict}
    """

    implements(IMUCClient)

    timeout = None

    def __init__(self):
        XMPPHandler.__init__(self)

        self._rooms = {}
        self._deferreds = []


    def connectionInitialized(self):
        """
        This method is called when the client has successfully authenticated.
        It initializes several xpath events to handle MUC stanzas that come in.
        After those are initialized then the method initialized is called to signal that we have finished.
        """
        self.xmlstream.addObserver(PRESENCE+"[not(@type) or @type='available']/x", self._onXPresence)
        self.xmlstream.addObserver(PRESENCE+"[@type='unavailable']", self._onUnavailablePresence)
        self.xmlstream.addObserver(PRESENCE+"[@type='error']", self._onPresenceError)
        self.xmlstream.addObserver(GROUPCHAT, self._onGroupChat)
        self.xmlstream.addObserver(SUBJECT, self._onSubject)
        # add history

        self.initialized()


    def _addRoom(self, room):
        """
        Add a room to the room collection.

        Rooms are stored by the JID of the room itself. I.e. it uses the Room
        ID and service parts of the Room JID.

        @note: An entity can only join a particular room once.
        """
        bareRoomJID = room.roomJID.userhostJID()
        self._rooms[bareRoomJID] = room


    def _getRoom(self, roomJID):
        """
        Grab a room from the room collection.

        This uses the Room ID and service parts of the given JID to look up
        the L{Room} instance associated with it.
        """
        bareRoomJID = roomJID.userhostJID()
        return self._rooms.get(bareRoomJID)


    def _removeRoom(self, roomJID):
        """
        Delete a room from the room collection.
        """
        bareRoomJID = roomJID.userhostJID()
        if bareRoomJID in self._rooms:
            del self._rooms[bareRoomJID]


    def _onUnavailablePresence(self, prs):
        """
        This method is called when the stanza matches the xpath observer.
        The client has received a presence stanza with the 'type' attribute of unavailable.
        It means a user has exited a MUC room.
        """

        if not prs.hasAttribute('from'):
            return
        room_jid = jid.internJID(prs.getAttribute('from', ''))
        self._userLeavesRoom(room_jid)


    def _onPresenceError(self, prs):
        """
        This method is called when a presence stanza with the 'type' attribute of error.
        There are various reasons for receiving a presence error and it means that the user has left the room.
        """
        if not prs.hasAttribute('from'):
            return
        room_jid = jid.internJID(prs.getAttribute('from', ''))
        # add an error hook here?
        self._userLeavesRoom(room_jid)


    def _getExceptionFromElement(self, stanza):
        # find an exception based on the error stanza
        muc_condition = 'exception'

        error = getattr(stanza, 'error', None)
        if error is not None:
            for e in error.elements():
                muc_condition = e.name

        return MUC_EXCEPTIONS[muc_condition]


    def _userLeavesRoom(self, room_jid):
        # when a user leaves a room we need to update it
        room = self._getRoom(room_jid)
        if room is None:
            # not in the room yet
            return
        # check if user is in roster
        user = room.getUser(room_jid.resource)
        if user is None:
            return
        if room.inRoster(user):
            room.removeUser(user)
            self.userLeftRoom(room, user)


    def _onXPresence(self, prs):
        """
        A muc presence has been received.
        """
        if not prs.hasAttribute('from'):
            return
        room_jid = jid.internJID(prs.getAttribute('from', ''))

        status = getattr(prs, 'status', None)
        show = getattr(prs, 'show', None)

        # grab room
        room = self._getRoom(room_jid)
        if room is None:
            # not in the room yet
            return
        user = self._changeUserStatus(room, room_jid, status, show)

        if room.inRoster(user):
            # we changed status or nick
            muc_status = getattr(prs.x, 'status', None)
            if muc_status:
                code = muc_status.getAttribute('code', 0)
            else:
                self.userUpdatedStatus(room, user, show, status)
        else:
            room.addUser(user)
            self.userJoinedRoom(room, user)


    def _onGroupChat(self, msg):
        """
        A group chat message has been received from a MUC room.

        There are a few event methods that may get called here. receviedGroupChat and receivedHistory
        """
        if not msg.hasAttribute('from'):
            # need to return an error here
            return
        room_jid = jid.internJID(msg.getAttribute('from', ''))

        room = self._getRoom(room_jid)
        if room is None:
            # not in the room yet
            return
        user = room.getUser(room_jid.resource)
        delay = None
        # need to check for delay and x stanzas for delay namespace for backwards compatability
        for e in msg.elements():
            if e.uri == NS_DELAY or e.uri == NS_JABBER_DELAY:
                delay = e
        body = unicode(msg.body)
        # grab room
        if delay is None:
            self.receivedGroupChat(room, user, body)
        else:
            self.receivedHistory(room, user, body, delay['stamp'], frm=delay.getAttribute('from',None))


    def _onSubject(self, msg):
        """
        A subject has been sent from a MUC room.
        """
        if not msg.hasAttribute('from'):
            return
        room_jid = jid.internJID(msg['from'])

        # grab room
        room = self._getRoom(room_jid)
        if room is None:
            # not in the room yet
            return

        self.receivedSubject(room_jid, unicode(msg.subject))


    def _makeTimeStamp(self, stamp=None):
        # create a timestamp
        if stamp is None:
            stamp = datetime.datetime.now()

        return stamp.strftime('%Y%m%dT%H:%M:%S')


    def _joinedRoom(self, d, prs):
        """
        We have presence that says we joined a room.
        """
        roomJID = jid.internJID(prs['from'])

        # check for errors
        if prs.hasAttribute('type') and prs['type'] == 'error':
            d.errback(self._getExceptionFromElement(prs))
        else:
            # change the state of the room
            room = self._getRoom(roomJID)
            if room is None:
                raise NotFound
            room.state = 'joined'

            # grab status
            status = getattr(prs.x, 'status', None)
            if status:
                room.status = status.getAttribute('code', None)

            d.callback(room)


    def _leftRoom(self, d, prs):
        """
        We have presence that says we left a room.
        """
        roomJID = jid.internJID(prs['from'])

        # check for errors
        if prs.hasAttribute('type') and prs['type'] == 'error':
            d.errback(self._getExceptionFromElement(prs))
        else:
            # change the state of the room
            room = self._getRoom(roomJID)
            if room is None:
                raise NotFound
            self._removeRoom(roomJID)

            d.callback(True)


    def initialized(self):
        """
        Client is initialized and ready!
        """
        pass


    def userJoinedRoom(self, room, user):
        """
        User has joined a MUC room.

        This method will need to be modified inorder for clients to
        do something when this event occurs.

        @param room: The room the user has joined.
        @type  room: L{Room}

        @param user: The user that joined the MUC room.
        @type  user: L{User}

        """
        pass


    def userLeftRoom(self, room, user):
        """
        User has left a room.

        This method will need to be modified inorder for clients to
        do something when this event occurs.

        @param room: The room the user has joined.
        @type  room: L{Room}

        @param user: The user that joined the MUC room.
        @type  user: L{User}

        """
        pass


    def userUpdatedStatus(self, room, user, show, status):
        """
        User Presence has been received

        This method will need to be modified inorder for clients to
        do something when this event occurs.

        """
        pass


    def receivedSubject(self, room, subject):
        """
        This method will need to be modified inorder for clients to
        do something when this event occurs.

        """
        pass


    def receivedHistory(self, room, user, message, history, frm=None):
        """
        This method will need to be modified inorder for clients to
        do something when this event occurs.
        """
        pass


    def _cbDisco(self, iq):
        # grab query

        return getattr(iq,'query', None)


    def sendDeferred(self,  obj, timeout):
        """
        Send data or a domish element, adding a deferred with a timeout.

        @param obj: The object to send over the wire.
        @type  obj: L{domish.Element} or L{unicode}

        @param timeout: The number of seconds to wait before the deferred is timed out.
        @type  timeout: L{int}

        The deferred object L{defer.Deferred} is returned.
        """
        d = defer.Deferred()
        self._deferreds.append(d)


        def onTimeout():
            i = 0
            for xd in self._deferreds:
                if d == xd:
                    self._deferreds.pop(i)
                    d.errback(xmlstream.TimeoutError("Timeout waiting for response."))
                i += 1

        call = reactor.callLater(timeout, onTimeout)

        def cancelTimeout(result):
            if call.active():
                call.cancel()

            return result

        d.addBoth(cancelTimeout)

        self.xmlstream.send(obj)
        return d


    def configure(self, room_jid, fields=[]):
        """
        Configure a room

        @param room_jid: The room jabber/xmpp entity id for the requested configuration form.
        @type  room_jid: L{jid.JID}

        @param fields: The fields we want to modify.
        @type  fields: A L{list} or L{dataform.Field}

        """
        request = ConfigureRequest(self.xmlstream, method='set', fields=fields)
        request['to'] = room_jid

        return request.send()


    def getConfigureForm(self, room_jid):
        """
        Grab the configuration form from the room. This sends an iq request to the room.

        @param room_jid: The room jabber/xmpp entity id for the requested configuration form.
        @type  room_jid: L{jid.JID}

        """
        request = ConfigureRequest(self.xmlstream)
        request['to'] = room_jid
        return request.send()


    def join(self, service, roomIdentifier, nick, history=None):
        """
        Join a MUC room by sending presence to it.

        @param server: The server where the room is located.
        @type  server: L{unicode}
        @param room: The room name the entity is joining.
        @type  room: L{unicode}
        @param nick: The nick name for the entitity joining the room.
        @type  nick: L{unicode}
        @param history: The maximum number of history stanzas you would like.

        @return: A deferred that fires when the entity is in the room or an
                 error has occurred.
        """
        room = Room(roomIdentifier, service, nick, state='joining')
        self._addRoom(room)

        p = BasicPresence(to=room.roomJID)
        if history is not None:
            p.x.addChild(history.toElement())

        d = self.sendDeferred(p, timeout=DEFER_TIMEOUT)

        # add observer for joining the room
        query = PRESENCE + u"[@from='%s']" % room.roomJID
        self.xmlstream.addOnetimeObserver(query, self._joinedRoom, 1, d)

        return d


    def _changeUserStatus(self, room, roomJID, status, show):
        """
        Change the user status in a room.
        """

        # check if user is in roster
        user = room.getUser(roomJID.resource)
        if user is None: # create a user that does not exist
            user = User(roomJID.resource)

        if status is not None:
            user.status = unicode(status)
        if show is not None:
            user.show = unicode(show)

        return user


    def _changed(self, d, roomJID, prs):
        """
        Callback for changing the nick and status.
        """

        status = getattr(prs, 'status', None)
        show = getattr(prs, 'show', None)

        room = self._getRoom(roomJID)

        user = self._changeUserStatus(room, roomJID, status, show)

        d.callback(room)


    def nick(self, bareRoomJID, new_nick):
        """
        Change an entities nick name in a MUC room.

        See: http://xmpp.org/extensions/xep-0045.html#changenick

        @param bareRoomJID: The JID of the room, i.e. without a resource.
        @type bareRoomJID: L{jid.JID}

        @param new_nick: The nick name for the entitity joining the room.
        @type new_nick: L{unicode}

        """


        room = self._getRoom(bareRoomJID)
        if room is None:
            raise NotFound

        # Change the nickname
        room.nick = new_nick
        room.refreshRoomJID()

        # Create presence
        p = BasicPresence(to=room.roomJID)
        d = self.sendDeferred(p, timeout=DEFER_TIMEOUT)

        # Add observer for joining the room
        query = PRESENCE+"[@from='%s']" % (room.roomJID.full())
        self.xmlstream.addOnetimeObserver(query, self._changed, 1, d, bareRoomJID)

        return d


    def leave(self, roomJID):
        """
        Leave a MUC room.

        See: http://xmpp.org/extensions/xep-0045.html#exit

        @param roomJID: The Room JID of the room to leave.
        @type roomJID: L{jid.JID}

        """
        room = self._getRoom(roomJID)

        p = xmppim.UnavailablePresence(to=room.roomJID)

        d = self.sendDeferred(p, timeout=DEFER_TIMEOUT)
        # add observer for joining the room
        query = PRESENCE + u"[@from='%s' and @type='unavailable']" % (room.roomJID)
        self.xmlstream.addOnetimeObserver(query, self._leftRoom, 1, d)

        return d


    def status(self, roomJID, show=None, status=None):
        """
        Change user status.

        See: http://xmpp.org/extensions/xep-0045.html#changepres

        @param roomJID: The room jabber/xmpp entity id for the requested configuration form.
        @type  roomJID: L{jid.JID}

        @param show: The availability of the entity. Common values are xa, available, etc
        @type  show: L{unicode}

        @param show: The current status of the entity.
        @type  show: L{unicode}

        """
        room = self._getRoom(roomJID)
        if room is None:
            raise NotFound

        p = BasicPresence(to=room.roomJID)
        if status is not None:
            p.addElement('status', None, status)

        if show is not None:
            p.addElement('show', None, show)

        d = self.sendDeferred(p, timeout=DEFER_TIMEOUT)

        # add observer for joining the room
        query = PRESENCE + u"[@from='%s']" % room.roomJID
        self.xmlstream.addOnetimeObserver(query, self._changed, 1, d, roomJID)

        return d


    def _sendMessage(self, msg, children=None):
        """
        Send a message.
        """
        if children:
            for child in children:
                msg.addChild(child)

        self.xmlstream.send(msg)


    def groupChat(self, to, message, children=None):
        """
        Send a groupchat message
        """
        msg = GroupChat(to, body=message)

        self._sendMessage(msg, children=children)


    def chat(self, room_jid, message, children=None):
        """
        Send a private chat message to a user in a MUC room.

        See: http://xmpp.org/extensions/xep-0045.html#privatemessage

        @param room_jid: The room entity id.
        @type  room_jid: L{jid.JID}

        """

        msg = PrivateChat(room_jid, body=message)

        self._sendMessage(msg, children=children)


    def invite(self, bareRoomJID, reason=None, invitee=None):
        """
        Invite a xmpp entity to a MUC room.

        See: http://xmpp.org/extensions/xep-0045.html#invite

        @param bareRoomJID: The bare JID of the room.
        @type bareRoomJID: L{jid.JID}
        @param reason: The reason for the invite.
        @type reason: L{unicode}
        @param invitee: The entity that is being invited.
        @type invitee: L{jid.JID}

        """
        msg = InviteMessage(bareRoomJID, reason=reason, invitee=invitee)
        self._sendMessage(msg)


    def password(self, room_jid, password):
        """
        Send a password to a room so the entity can join.

        See: http://xmpp.org/extensions/xep-0045.html#enter-pw

        @param room_jid: The room entity id.
        @type  room_jid: L{jid.JID}

        @param password: The MUC room password.
        @type  password: L{unicode}

        """
        p = PasswordPresence(room_jid, password)

        self.xmlstream.send(p)


    def register(self, room_jid, fields=[]):
        """
        Send a request to register for a room.

        @param room_jid: The room entity id.
        @type  room_jid: L{jid.JID}

        @param fields: The fields you need to register.
        @type  fields: L{list} of L{dataform.Field}

        """
        iq = RegisterRequest(self.xmlstream, method='set', fields=fields)
        iq['to'] = room_jid.userhost()
        return iq.send()


    def _getAffiliationList(self, room_jid, affiliation):
        # send a request for an affiliation list in a room.
        iq = AffiliationRequest(self.xmlstream,
                                method='get',
                                affiliation=affiliation,
                                )
        iq['to'] = room_jid.full()
        return iq.send()


    def _getRoleList(self, room_jid, role):
        # send a role request
        iq = RoleRequest(self.xmlstream,
                                method='get',
                                role=role,
                                )
        iq['to'] = room_jid.full()
        return iq.send()


    def _setAffiliationList(self, iq, affiliation, roomJID):
        # set a rooms affiliation list
        room = self._getRoom(roomJID)
        if room is not None:
            affiliation_list = []
            setattr(room, affiliation, [])

            for item in iq.query.elements():
                nick = item.getAttribute('nick', None)
                entity = item.getAttribute('jid', None)
                role = item.getAttribute('role', None)
                user = None
                if nick is None and entity is None:
                    raise Exception, 'bad attributes in item list'
                if nick is not None:
                    user = room.getUser(nick)
                if user is None:
                    user = User(nick, entity=jid.internJID(entity))
                    user.affiliation = 'member'
                if role is not None:
                    user.role = role

                affiliation_list.append(user)

            setattr(room, affiliation, affiliation_list)
        return room


    def getMemberList(self, bareRoomJID):
        """
        Get the member list of a room.

        @param bareRoomJID: The bare JID of the room.
        @type  bareRoomJID: L{jid.JID}

        """
        d = self._getAffiliationList(bareRoomJID, 'member')
        d.addCallback(self._setAffiliationList, 'members', bareRoomJID)
        return d


    def getAdminList(self, bareRoomJID):
        """
        Get the admin list of a room.

        @param bareRoomJID: The bare JID of the room.
        @type  bareRoomJID: L{jid.JID}

        """
        d = self._getAffiliationList(bareRoomJID, 'admin')
        d.addCallback(self._setAffiliationList, 'admin', bareRoomJID)
        return d


    def getBanList(self, bareRoomJID):
        """
        Get an outcast list from a room.

        @param bareRoomJID: The bare JID of the room.
        @type  bareRoomJID: L{jid.JID}

        """
        d = self._getAffiliationList(bareRoomJID, 'outcast')
        d.addCallback(self._setAffiliationList, 'outcast', bareRoomJID)
        return d


    def getOwnerList(self, bareRoomJID):
        """
        Get an owner list from a room.

        @param bareRoomJID: The room jabber/xmpp entity id for the requested member list.
        @type  bareRoomJID: L{jid.JID}

        """
        d = self._getAffiliationList(bareRoomJID, 'owner')
        d.addCallback(self._setAffiliationList, 'owner', bareRoomJID)
        return d


    def getRegisterForm(self, room):
        """
        Grab the registration form for a MUC room.

        @param room: The room jabber/xmpp entity id for the requested registration form.
        @type  room: L{jid.JID}

        """
        iq = RegisterRequest(self.xmlstream)
        iq['to'] = room.userhost()
        return iq.send()


    def destroy(self, room_jid, reason=None):
        """
        Destroy a room.

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @ivar reason: The reason we are destroying the room.
        @type reason: L{unicode}

        """
        def destroyed(iq):
            self._removeRoom(room_jid)
            return True

        iq = OwnerRequest(self.xmlstream, method='set')
        d = iq.query.addElement('destroy')
        d['jid'] = room_jid.userhost()
        if reason is not None:
            d.addElement('reason', None, reason)

        return iq.send().addCallback(destroyed)


    def subject(self, room_jid, subject):
        """
        Change the subject of a MUC room.

        See: http://xmpp.org/extensions/xep-0045.html#subject-mod

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param subject: The subject you want to set.
        @type  subject: L{unicode}

        """
        msg = GroupChat(room_jid, subject=subject)
        self.xmlstream.send(msg)


    def voice(self, room_jid):
        """
        Request voice for a moderated room.

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        """
        msg = MessageVoice(to=room_jid)
        self.xmlstream.send(msg)


    def history(self, room_jid, message_list):
        """
        Send history to create a MUC based on a one on one chat.

        See: http://xmpp.org/extensions/xep-0045.html#continue

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param message_list: A list of history to send to the room.
        @type  message_list: L{list} of L{domish.Element}

        """

        for m in message_list:
            m['type'] = 'groupchat'
            mto = m['to']
            frm = m.getAttribute('from', None)
            m['to'] = room_jid.userhost()

            d = m.addElement('delay', NS_DELAY)
            d['stamp'] = self._makeTimeStamp()
            d['from'] = mto

            self.xmlstream.send(m)


    def _setAffiliation(self, frm, room_jid, affiliation, reason=None, a_jid=None, nick=None):
        # Send an affiliation request to change an entities affiliation to a MUC room.
        iq = AffiliationRequest(self.xmlstream,
                                method='set',
                                affiliation=affiliation,
                                a_jid=a_jid,
                                nick=nick,
                                reason=reason)
        iq['to'] = room_jid.userhost() # this is a room jid, only send to room
        iq['from'] = frm.full()
        return iq.send()


    def _setRole(self, frm, room_jid, a_jid=None, reason=None, role='none', nick=None):
        # send a role request
        iq = RoleRequest(self.xmlstream,
                         method='set',
                         a_jid=a_jid,
                         role=role,
                         nick=nick,
                         reason=reason)

        iq['to'] = room_jid.userhost() # this is a room jid, only send to room
        iq['from'] = frm.full()
        return iq.send()


    def _cbRequest(self, room_jid, iq):
        r = self._getRoom(room_jid)
        if r is None:
            raise NotFound

        return r


    def modifyAffiliationList(self, frm, room_jid, jid_list, affiliation):
        """
        Modify an affiliation list.

        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param jid_list: The list of jabber ids to change in a room. This can be a nick or a full jid.
        @type  jid_list: L{list} of L{unicode} for nicks. L{list} of L{jid.JID} for jids.

        @param affiliation: The affilation to change.
        @type  affiliation: L{unicode}


        """
        iq = AffiliationRequest(self.xmlstream,
                                method='set',
                                affiliation=affiliation,
                                )
        iq.items(jid_list)
        iq['to'] = room_jid.userhost() # this is a room jid, only send to room
        iq['from'] = frm.full()
        return iq.send()


    def grantVoice(self, frm, room_jid, voice_jid=None, reason=None, nick=None):
        """
        Grant voice to an entity.

        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param reason: The reason for granting voice to the entity.
        @type  reason: L{unicode}

        @param nick: The nick name for the client in this room.
        @type  nick: L{unicode}

        """
        return self._setRole(frm, room_jid, role='participant', a_jid=voice_jid, nick=nick, reason=reason)


    def grantVisitor(self, frm, room_jid, reason=None, nick=None):
        """
        Change a participant to a visitor. This will disallow the entity to send messages to a moderated room.
        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param reason: The reason for granting voice to the entity.
        @type  reason: L{unicode}

        @param nick: The nick name for the client in this room.
        @type  nick: L{unicode}

        """
        return self._setRole(frm, room_jid, role='visitor', reason=reason, nick=nick)


    def grantModerator(self, frm, room_jid, reason=None, nick=None):
        """
        Grant moderator priviledges to a MUC room.

        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        """
        return self._setRole(frm, room_jid, role='moderator', reason=reason, nick=nick)


    def ban(self, room_jid, ban_jid, frm, reason=None, nick=None):
        """
        Ban a user from a MUC room.

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param ban_jid: The room jabber/xmpp entity id.
        @type  ban_jid: L{jid.JID}

        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param reason: The reason for banning the entity.
        @type  reason: L{unicode}

        @param nick: The nick name for the client in this room.
        @type  nick: L{unicode}

        """
        return self._setAffiliation(frm, room_jid, 'outcast', nick=nick, a_jid=ban_jid, reason=reason)


    def kick(self, room_jid, kick_jid, frm, reason=None, nick=None):
        """
        Kick a user from a MUC room.

        @param room_jid: The room jabber/xmpp entity id.
        @type  room_jid: L{jid.JID}

        @param kick_jid: The room jabber/xmpp entity id.
        @type  kick_jid: L{jid.JID}

        @param frm: The entity sending the request.
        @type  frm: L{jid.JID}

        @param reason: The reason given for the kick.
        @type  reason: L{unicode}

        @param nick: The nick for the user in the MUC room.
        @type  nick: L{unicode}

        """
        return self._setAffiliation(frm, room_jid, 'none', a_jid=kick_jid, nick=nick, reason=reason)