Changeset 113:cb4051e2f51a


Ignore:
Timestamp:
Oct 7, 2008, 11:47:13 PM (13 years ago)
Author:
Christopher Zorn <tofu@…>
Branch:
wokkel-muc-client-support-24
Convert:
svn:b33ecbfc-034c-dc11-8662-000475d9059e/branches/wokkel-muc-client-support-24@83
Message:

some documentation and additions to the interface, also some more abstraction and tests

Location:
wokkel
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • wokkel/iwokkel.py

    r107 r113  
    516516    """
    517517    Multi-User Chat Client
    518     """
    519 
     518
     519    A client interface to XEP-045 : http://xmpp.org/extensions/xep-0045.html
     520
     521    """
     522
     523    def receivedSubject(room, subject):
     524        """
     525        A subject is received when you join a room and when the subject is changed. This
     526        method is triggered by one of those two events.
     527
     528        @param room: The room the subject was accepted for.
     529        @type room: L{muc.Room}
     530
     531        @param subject: The subject of the given room.
     532        @type subject: C{unicode}
     533        """
     534
     535
     536    def receivedHistory(room, user, message, history, frm=None):
     537        """
     538        Past messages from a chat room has been received. This occurs when you join a room.
     539
     540
     541        """
     542
     543   
     544    def disco(entity, type='info'):
     545        """Send disco queries to a XMPP entity
     546
     547        @param entity: A XMPP entity to send the disco request to.
     548        @type entity: C{unicode}
     549
     550        @param type: Optional argument to determine the type of discovery being done.
     551        @type type: C{str}
     552
     553        """
     554
     555       
     556
     557    def configure(room_jid, fields=[]):
     558        """Configure a room. When a user has administration privledges they can configure
     559        a room.
     560
     561        @param room_jid: A XMPP entity for the room.
     562        @type room_jid: L{jid.JID}
     563
     564        @param fields: A list of fields to change or add to the room's configuration.
     565        @type fields: C{list}
     566
     567        """
     568
     569    def getConfigureForm(room_jid):
     570        """
     571        In order to know the fields to change in a room you will need to get the form.
     572       
     573        @param room_jid: The room you want the configuration form from.
     574        @type room_jid: L{jid.JID}
     575
     576        """
     577
     578    def join(server, room, nick):
     579        """
     580        Join a multi-user chat room.
     581
     582        @param server: The server the room is on.
     583        @type server: C{str}
     584
     585        @param room: The room name.
     586        @type room: C{str}
     587       
     588        @param nick: The nick name you want when you join the room.
     589        @type nick: C{str}
     590
     591        """
     592
     593
     594    def leave(room_jid):
     595        """
     596        Leave a multi-user chat room.
     597
     598        @param room_jid: The room you want the configuration form from.
     599        @type room_jid: L{jid.JID}
     600
     601        """
     602
     603    def userJoinedRoom(room, user):
     604        """User has joined the room.
     605
     606        @param room: The room the user joined.
     607        @type  room: L{muc.Room}
     608
     609        @param user: The user that joined the room.
     610        @type  user: L{muc.User}
     611
     612        """
     613   
     614
     615    def groupChat(to, message, children=None):
     616        """Send a groupchat message to a room.
     617
     618        """
     619
     620
     621    def chat(to, message, children=None):
     622        """
     623
     624        """
     625
     626
     627    def password(to, password):
     628        """
     629        """
     630   
     631    def register(to, fields=[]):
     632        """
     633        """
     634
     635
     636    def subject(to, subject):
     637        """
     638        """
     639
     640    def voice(to):
     641        """
     642        """
     643
     644
     645    def history(to, message_list):
     646        """
     647        """
     648
     649    def ban(to, ban_jid, frm, reason=None):
     650        """
     651        """
     652
     653
     654    def kick(to, kick_jid, frm, reason=None):
     655        """
     656        """
     657
  • wokkel/muc.py

    r112 r113  
    6666
    6767GROUPCHAT     = MESSAGE +'[@type="groupchat"]/body'
    68 SUBJECT       = MESSAGE +'[@type="groupchat"]/body'
     68SUBJECT       = MESSAGE +'[@type="groupchat"]/subject'
    6969MESSAGE_ERROR = MESSAGE +'[@type="error"]'
    7070
     
    121121    Configure MUC room request.
    122122
     123    http://xmpp.org/extensions/xep-0045.html#roomconfig
     124
    123125    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
    124126    @type method: C{str}
     
    243245            d['from'] = h_frm
    244246
     247class User(object):
     248    """
     249    A user/entity in a multi-user chat room.
     250    """
     251   
     252    def __init__(self, nick, user_jid=None):
     253        self.nick = nick
     254        self.user_jid = user_jid
     255        self.affiliation = 'none'
     256        self.role = 'none'
     257       
     258        self.status = None
     259        self.show   = None
     260
     261
    245262class Room(object):
    246263    """
     
    261278               
    262279        self.roster = {}
     280
     281       
     282
     283    def addUser(self, user):
     284        """
     285        """
     286        self.roster[user.nick.lower()] = user
     287
     288    def inRoster(self, user):
     289        """
     290        """
     291
     292        return self.roster.has_key(user.nick.lower())
     293
     294    def getUser(self, nick):
     295        """
     296        """
     297        return self.roster.get(nick.lower())
    263298
    264299       
     
    341376
    342377    def connectionInitialized(self):
    343         self.xmlstream.addObserver(PRESENCE+"/x", self._onXPresence)
     378        self.xmlstream.addObserver(PRESENCE+"[not(@type) or @type='available']/x", self._onXPresence)
     379        self.xmlstream.addObserver(PRESENCE+"[@type='unavailable']", self._onUnavailablePresence)
     380        self.xmlstream.addObserver(PRESENCE+"[@type='error']", self._onPresenceError)
    344381        self.xmlstream.addObserver(GROUPCHAT, self._onGroupChat)
    345382        self.xmlstream.addObserver(SUBJECT, self._onSubject)
     
    356393            del self.rooms[room_jid.full().lower()]
    357394
     395
     396    def _onUnavailablePresence(self, prs):
     397        """
     398        """
     399        if not prs.hasAttribute('from'):
     400            return
     401        room_jid = jid.internJID(prs.getAttribute('from', ''))
     402
     403
     404    def _onPresenceError(self, prs):
     405        """
     406        """
     407        if not prs.hasAttribute('from'):
     408            return
     409        room_jid = jid.internJID(prs.getAttribute('from', ''))
     410
     411
    358412    def _onXPresence(self, prs):
    359413        """
    360414        """
    361         if prs.x.uri == NS_USER:
    362             self.receivedUserPresence(prs)
     415        if not prs.hasAttribute('from'):
     416            return
     417        room_jid = jid.internJID(prs.getAttribute('from', ''))
     418           
     419        status = getattr(prs, 'status', None)
     420        show   = getattr(prs, 'show', None)
     421       
     422        # grab room
     423        room = self._getRoom(room_jid)
     424        if room is None:
     425            # not in the room yet
     426            return
     427
     428        # check if user is in roster
     429        user = room.getUser(room_jid.resource)
     430        if user is None: # create a user that does not exist
     431            user = User(room_jid.resource)
     432           
     433       
     434        if room.inRoster(user):
     435            # we changed status or nick
     436            muc_status = getattr(prs.x, 'status', None)
     437            if muc_status:
     438                code = muc_status.getAttribute('code', 0)
     439            else:
     440                self.userUpdatedStatus(room, user, show, status)
     441        else:           
     442            room.addUser(user)
     443            self.userJoinedRoom(room, user)
    363444           
    364445
     
    366447        """
    367448        """
     449        if not msg.hasAttribute('from'):
     450            # need to return an error here
     451            return
     452        room_jid = jid.internJID(msg.getAttribute('from', ''))
     453
     454        room = self._getRoom(room_jid)
     455        if room is None:
     456            # not in the room yet
     457            return
     458        user = room.getUser(room_jid.resource)
     459
    368460        delay = getattr(msg, 'delay', None)
     461        body  = unicode(msg.body)
     462        # grab room
    369463        if delay is None:
    370             self.receivedGroupChat(msg)
     464            self.receivedGroupChat(room, user, body)
    371465        else:
    372             self.receivedHistory(msg)
     466            self.receivedHistory(room, user, body, delay['stamp'], frm=delay.getAttribute('from',None))
    373467
    374468
     
    376470        """
    377471        """
    378         self.receivedSubject(msg)
     472        if not msg.hasAttribute('from'):
     473            return
     474        room_jid = jid.internJID(msg['from'])
     475
     476        # grab room
     477        room = self._getRoom(room_jid)
     478        if room is None:
     479            # not in the room yet
     480            return
     481
     482        self.receivedSubject(room_jid, unicode(msg.subject))
    379483
    380484
     
    426530            d.callback(True)
    427531
    428     def receivedUserPresence(self, prs):
     532    def userJoinedRoom(self, room, user):
     533        """User has joined a room
     534        """
     535        pass
     536
     537
     538    def userUserUpdatedStatus(self, room, user, show, status):
    429539        """User Presence has been received
    430540        """
     
    432542       
    433543
    434     def receivedSubject(self, msg):
     544    def receivedSubject(self, room, subject):
    435545        """
    436546        """
     
    438548
    439549
    440     def receivedHistory(self, msg):
     550    def receivedHistory(self, room, user, message, history, frm=None):
    441551        """
    442552        """
     
    533643       
    534644    def invite(self, to, reason=None, full_jid=None):
     645        """
     646        """
    535647        msg = InviteMessage(to, reason=reason, full_jid=full_jid)
    536648        self._sendMessage(msg)
     
    547659        return iq.send()
    548660
    549     def getRegisterForm(self, to):
     661    def getRegisterForm(self, room):
     662        """
     663        """
    550664        iq = RegisterRequest(self.xmlstream)
    551         iq['to'] = to
     665        iq['to'] = room.userhost()
    552666        return iq.send()
    553667
  • wokkel/test/test_muc.py

    r112 r113  
    5757        self.user_jid = JID('test@jabber.org/Testing')
    5858
     59    def _createRoom(self):
     60        # create a room
     61        self.current_room = muc.Room(self.test_room, self.test_srv, self.test_nick)
     62        self.protocol._setRoom(self.current_room)
     63
     64
    5965    def test_interface(self):
    6066        """
     
    6470
    6571
    66     def test_presence(self):
    67         """Test receiving room presence
     72    def test_userJoinedRoom(self):
     73        """Test receiving a user joined event.
    6874        """
    6975        p = muc.UserPresence()
     76        p['to'] = self.user_jid.full()
     77        p['from'] = self.room_jid.full()
     78
     79        # create a room
     80        self._createRoom()
     81
     82        def userPresence(room, user):
     83            self.failUnless(room.name==self.test_room, 'Wrong room name')
     84            self.failUnless(room.inRoster(user), 'User not in roster')
     85                           
    7086       
    71         def userPresence(prs):
    72             self.failUnless(len(prs.children)==1, 'Not enough children')
    73             self.failUnless(getattr(prs,'x',None), 'No x element')
    74                    
    75        
    76         d, self.protocol.receivedUserPresence = calledAsync(userPresence)
     87        d, self.protocol.userJoinedRoom = calledAsync(userPresence)
    7788        self.stub.send(p)
    7889        return d
     
    8394        """
    8495        m = muc.GroupChat('test@test.com',body='test')
    85        
    86         def groupChat(elem):
    87             self.failUnless(elem.name=='message','Wrong stanza')
    88             self.failUnless(elem['type'] == 'groupchat', 'Wrong attribute')
     96        m['from'] = self.room_jid.full()
     97
     98        self._createRoom()
     99
     100        def groupChat(room, user, message):
     101            self.failUnless(message=='test', "Wrong group chat message")
     102            self.failUnless(room.name==self.test_room, 'Wrong room name')
    89103                           
    90104       
     
    230244        return d
    231245
    232         self.fail('Not Implemented')
    233246       
    234247
     
    248261        """
    249262        m = muc.HistoryMessage(self.room_jid.userhost(), self.protocol._makeTimeStamp(), body='test')
    250        
    251         def roomHistory(h):
    252             self.failUnless(getattr(h,'delay',None), 'No delay element')
     263        m['from'] = self.room_jid.full()
     264       
     265        self._createRoom()
     266
     267        def roomHistory(room, user, body, stamp, frm=None):
     268            self.failUnless(body=='test', "wrong message body")
     269            self.failUnless(stamp, 'Does not have a history stamp')
    253270                   
    254271
Note: See TracChangeset for help on using the changeset viewer.