Resolve timeout errors for get_roster.

See issue #89

Using get_roster will now return the same types of values as
Iq.send. If a timeout occurs, then the event 'roster_timeout'
will be fired. A successful call to get_roster will also
raise the 'roster_received' event.

To ensure that the get_roster call was successful, here
is a pattern to follow:

    def __init__(self, ...):
        ...
        self.add_event_handler('session_start', self.session_start)
        self.add_event_handler('roster_timeout', self.roster_timeout)
        self.add_event_handler('roster_received', self.roster_received)

    def session_start(self, e):
        self.send_presence()
        self.get_roster()

    def roster_timeout(self, e):
        # Optionally increase the timeout period
        self.get_roster(timeout=self.response_timeout * 2)

    def roster_received(self, iq):
        # Do stuff, roster has been initialized.
        ...

tests/test_stream_roster.py

@@ -16,6 +16,13 @@ class TestStreamRoster(SleekTest):
         self.stream_start(mode='client')
         self.failUnless(self.xmpp.roster == {}, "Initial roster not empty.")
 
+        events = []
+
+        def roster_received(iq):
+            events.append('roster_received')
+
+        self.xmpp.add_event_handler('roster_received', roster_received)
+
         # Since get_roster blocks, we need to run it in a thread.
         t = threading.Thread(name='get_roster', target=self.xmpp.get_roster)
         t.start()
@@ -41,6 +48,9 @@ class TestStreamRoster(SleekTest):
         # Wait for get_roster to return.
         t.join()
 
+        # Give the event queue time to process.
+        time.sleep(.1)
+
         roster = {'user@localhost': {'name': 'User',
                                      'subscription': 'both',
                                      'groups': ['Friends', 'Examples'],
@@ -48,11 +58,20 @@ class TestStreamRoster(SleekTest):
                                      'in_roster': True}}
         self.failUnless(self.xmpp.roster == roster,
                 "Unexpected roster values: %s" % self.xmpp.roster)
+        self.failUnless('roster_received' in events,
+                "Roster received event not triggered: %s" % events)
 
     def testRosterSet(self):
         """Test handling pushed roster updates."""
         self.stream_start(mode='client')
         self.failUnless(self.xmpp.roster == {}, "Initial roster not empty.")
+        events = []
+
+        def roster_update(e):
+            events.append('roster_update')
+
+        self.xmpp.add_event_handler('roster_update', roster_update)
+
 
         self.recv("""
           <iq type="set" id="1">
@@ -72,6 +91,9 @@ class TestStreamRoster(SleekTest):
           </iq>
         """)
 
+        # Give the event queue time to process.
+        time.sleep(.1)
+
         roster = {'user@localhost': {'name': 'User',
                                      'subscription': 'both',
                                      'groups': ['Friends', 'Examples'],
@@ -79,7 +101,66 @@ class TestStreamRoster(SleekTest):
                                      'in_roster': True}}
         self.failUnless(self.xmpp.roster == roster,
                 "Unexpected roster values: %s" % self.xmpp.roster)
+        self.failUnless('roster_update' in events,
+                "Roster updated event not triggered: %s" % events)
 
+    def testRosterTimeout(self):
+        """Test handling a timed out roster request."""
+        self.stream_start()
+        events = []
+
+        def roster_timeout(event):
+            events.append('roster_timeout')
+
+        self.xmpp.add_event_handler('roster_timeout', roster_timeout)
+        self.xmpp.get_roster(timeout=0)
+
+        # Give the event queue time to process.
+        time.sleep(.1)
+
+        self.failUnless(events == ['roster_timeout'],
+                 "Roster timeout event not triggered: %s." % events)
+
+    def testRosterCallback(self):
+        """Test handling a roster request callback."""
+        self.stream_start()
+        events = []
+
+        def roster_callback(iq):
+            events.append('roster_callback')
+
+        # Since get_roster blocks, we need to run it in a thread.
+        t = threading.Thread(name='get_roster',
+                             target=self.xmpp.get_roster,
+                             kwargs={'callback': roster_callback})
+        t.start()
+
+        self.send("""
+          <iq type="get" id="1">
+            <query xmlns="jabber:iq:roster" />
+          </iq>
+        """)
+        self.recv("""
+          <iq type="result" id="1">
+            <query xmlns="jabber:iq:roster">
+              <item jid="user@localhost"
+                    name="User"
+                    subscription="both">
+                <group>Friends</group>
+                <group>Examples</group>
+              </item>
+            </query>
+          </iq>
+        """)
+
+        # Wait for get_roster to return.
+        t.join()
+
+        # Give the event queue time to process.
+        time.sleep(.1)
+
+        self.failUnless(events == ['roster_callback'],
+                 "Roster timeout event not triggered: %s." % events)