Changeset 128:db5de9ee45fa for wokkel/iwokkel.py

Timestamp:

Jun 4, 2009, 10:15:16 AM (11 years ago)

Author:

Ralph Meijer <ralphm@…>

Branch:

wokkel-muc-client-support-24

Parents:

127:1610e7a3b777 (diff), 60:e5e6ff37ea27 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge in trunk changes.

Files:

• wokkel/iwokkel.py (modified) (1 diff)
• wokkel/iwokkel.py (modified) (17 diffs)

wokkel/iwokkel.py

@@ -768 +768 @@
         @rtype: L{defer.Deferred}
         """
+
+
+
+class IMUCClient(Interface):
+    """
+    Multi-User Chat Client
+
+    A client interface to XEP-045 : http://xmpp.org/extensions/xep-0045.html
+
+    """
+
+    def receivedSubject(room, subject):
+        """
+        A subject is received when you join a room and when the subject is changed. This
+        method is triggered by one of those two events.
+
+        @param room: The room the subject was accepted for.
+        @type room: L{muc.Room}
+
+        @param subject: The subject of the given room.
+        @type subject: C{unicode}
+        """
+
+
+    def receivedHistory(room, user, message, history, frm=None):
+        """
+        Past messages from a chat room has been received. This occurs when you join a room.
+
+
+        """
+
+    
+    def disco(entity, type='info'):
+        """Send disco queries to a XMPP entity
+
+        @param entity: A XMPP entity to send the disco request to.
+        @type entity: C{unicode}
+
+        @param type: Optional argument to determine the type of discovery being done.
+        @type type: C{str}
+
+        """
+
+        
+
+    def configure(room_jid, fields=[]):
+        """Configure a room. When a user has administration privledges they can configure 
+        a room. 
+
+        @param room_jid: A XMPP entity for the room.
+        @type room_jid: L{jid.JID}
+
+        @param fields: A list of fields to change or add to the room's configuration.
+        @type fields: C{list}
+
+        """
+
+    def getConfigureForm(room_jid):
+        """
+        In order to know the fields to change in a room you will need to get the form.
+        
+        @param room_jid: The room you want the configuration form from.
+        @type room_jid: L{jid.JID}
+
+        """
+
+    def join(server, room, nick):
+        """
+        Join a multi-user chat room. 
+
+        @param server: The server the room is on.
+        @type server: C{str}
+
+        @param room: The room name.
+        @type room: C{str}
+        
+        @param nick: The nick name you want when you join the room.
+        @type nick: C{str}
+
+        """
+
+
+    def leave(room_jid):
+        """
+        Leave a multi-user chat room.
+
+        @param room_jid: The room you want the configuration form from.
+        @type room_jid: L{jid.JID}
+
+        """
+
+    def userJoinedRoom(room, user):
+        """User has joined the room.
+
+        @param room: The room the user joined.
+        @type  room: L{muc.Room}
+
+        @param user: The user that joined the room.
+        @type  user: L{muc.User}
+
+        """
+   
+
+    def groupChat(to, message, children=None):
+        """Send a groupchat message to a room.
+
+        """
+
+
+    def chat(to, message, children=None):
+        """
+
+        """
+
+
+    def password(to, password):
+        """
+        """
+    
+    def register(to, fields=[]):
+        """
+        """
+
+
+    def subject(to, subject):
+        """
+        """
+
+    def voice(to):
+        """
+        """
+
+
+    def history(to, message_list):
+        """
+        """
+
+    def ban(to, ban_jid, frm, reason=None):
+        """
+        """
+
+
+    def kick(to, kick_jid, frm, reason=None):
+        """
+        """

wokkel/iwokkel.py

@@ -16 +16 @@
     """
 
-    manager = Attribute("""XML stream manager""")
+    parent = Attribute("""XML stream manager for this handler""")
     xmlstream = Attribute("""The managed XML stream""")
 
@@ -26 +26 @@
         """
 
+
     def disownHandlerParent(parent):
         """
@@ -32 +33 @@
         @type parent: L{IXMPPHandlerCollection}
         """
+
 
     def makeConnection(xs):
@@ -45 +47 @@
         @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
         """
+
 
     def connectionMade():
@@ -55 +58 @@
         """
 
+
     def connectionInitialized():
         """
@@ -64 +68 @@
         """
 
+
     def connectionLost(reason):
         """
@@ -73 +78 @@
         @type reason: L{twisted.python.failure.Failure}
         """
+
 
 
@@ -87 +93 @@
         """
 
+
     def addHandler(handler):
         """
@@ -94 +101 @@
         """
 
+
     def removeHandler(handler):
         """
@@ -100 +108 @@
         @type handler: L{IXMPPHandler}
         """
+
 
 
@@ -270 +279 @@
         """
 
-    def notifyDelete(service, nodeIdentifier, subscriptions):
+
+    def notifyDelete(service, nodeIdentifier, subscribers,
+                     redirectURI=None):
         """
         Send out node deletion notifications.
@@ -278 +289 @@
         @param nodeIdentifier: The identifier of the node that was deleted.
         @type nodeIdentifier: C{unicode}
-        @param subscriptions: The subscriptions for which a notification should
-                              be sent out.
-        @type subscriptions: C{list} of L{jid.JID}
+        @param subscribers: The subscribers for which a notification should
+                            be sent out.
+        @type subscribers: C{list} of L{jid.JID}
+        @param redirectURI: Optional XMPP URI of another node that subscribers
+                            are redirected to.
+        @type redirectURI: C{str}
         """
 
@@ -387 +401 @@
         that option in a dictionary:
 
-        - C{'type'} (C{str}): The option's type (see
-          L{Field<wokkel.data_form.Field>}'s doc string for possible values).
-        - C{'label'} (C{unicode}): A human readable label for this option.
-        - C{'options'} (C{dict}): Optional list of possible values for this
-          option.
+         - C{'type'} (C{str}): The option's type (see
+           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
+         - C{'label'} (C{unicode}): A human readable label for this option.
+         - C{'options'} (C{dict}): Optional list of possible values for this
+           option.
 
         Example::
@@ -414 +428 @@
         """
 
-    def getDefaultConfiguration(requestor, service):
+    def getDefaultConfiguration(requestor, service, nodeType):
         """
         Called when a default node configuration request has been received.
@@ -422 +436 @@
         @param service: The entity the request was addressed to.
         @type service: L{jid.JID}
+        @param nodeType: The type of node for which the configuration is
+                         retrieved, C{'leaf'} or C{'collection'}.
+        @type nodeType: C{str}
         @return: A deferred that fires with a C{dict} representing the default
                  node configuration. Keys are C{str}s that represent the
@@ -511 +528 @@
         @type nodeIdentifier: C{unicode}
         """
+
+
+
+class IPubSubResource(Interface):
+
+    def locateResource(request):
+        """
+        Locate a resource that will handle the request.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        """
+
+
+    def getInfo(requestor, service, nodeIdentifier):
+        """
+        Get node type and meta data.
+
+        @param requestor: The entity the request originated from.
+        @type requestor: L{jid.JID}
+        @param service: The publish-subscribe service entity.
+        @type service: L{jid.JID}
+        @param nodeIdentifier: Identifier of the node to request the info for.
+        @type nodeIdentifier: L{unicode}
+        @return: A deferred that fires with a dictionary. If not empty,
+                 it must have the keys C{'type'} and C{'meta-data'} to keep
+                 respectively the node type and a dictionary with the meta
+                 data for that node.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def getNodes(requestor, service, nodeIdentifier):
+        """
+        Get all nodes contained by this node.
+
+        @param requestor: The entity the request originated from.
+        @type requestor: L{jid.JID}
+        @param service: The publish-subscribe service entity.
+        @type service: L{jid.JID}
+        @param nodeIdentifier: Identifier of the node to request the childs for.
+        @type nodeIdentifier: L{unicode}
+        @return: A deferred that fires with a list of child node identifiers.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def getConfigurationOptions():
+        """
+        Retrieve all known node configuration options.
+
+        The returned dictionary holds the possible node configuration options
+        by option name. The value of each entry represents the specifics for
+        that option in a dictionary:
+
+         - C{'type'} (C{str}): The option's type (see
+           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
+         - C{'label'} (C{unicode}): A human readable label for this option.
+         - C{'options'} (C{dict}): Optional list of possible values for this
+           option.
+
+        Example::
+
+            {
+            "pubsub#persist_items":
+                {"type": "boolean",
+                 "label": "Persist items to storage"},
+            "pubsub#deliver_payloads":
+                {"type": "boolean",
+                 "label": "Deliver payloads with event notifications"},
+            "pubsub#send_last_published_item":
+                {"type": "list-single",
+                 "label": "When to send the last published item",
+                 "options": {
+                     "never": "Never",
+                     "on_sub": "When a new subscription is processed"}
+                }
+            }
+
+        @rtype: C{dict}.
+        """
+
+
+    def publish(request):
+        """
+        Called when a publish request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: deferred that fires on success.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def subscribe(request):
+        """
+        Called when a subscribe request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a
+                 L{Subscription<wokkel.pubsub.Subscription>}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def unsubscribe(request):
+        """
+        Called when a subscribe request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with C{None} when unsubscription has
+                 succeeded.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def subscriptions(request):
+        """
+        Called when a subscriptions retrieval request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{list} of subscriptions as
+                 L{Subscription<wokkel.pubsub.Subscription>}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def affiliations(request):
+        """
+        Called when a affiliations retrieval request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{list} of affiliations as
+                 C{tuple}s of (node identifier as C{unicode}, affiliation state
+                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
+                 or C{'outcast'}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def create(request):
+        """
+        Called when a node creation request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{unicode} that represents
+                 the identifier of the new node.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def default(request):
+        """
+        Called when a default node configuration request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{dict} representing the default
+                 node configuration. Keys are C{str}s that represent the
+                 field name. Values can be of types C{unicode}, C{int} or
+                 C{bool}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def configureGet(request):
+        """
+        Called when a node configuration retrieval request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{dict} representing the node
+                 configuration. Keys are C{str}s that represent the field name.
+                 Values can be of types C{unicode}, C{int} or C{bool}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def configureSet(request):
+        """
+        Called when a node configuration change request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with C{None} when the node's
+                 configuration has been changed.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def items(request):
+        """
+        Called when a items retrieval request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with a C{list} of L{pubsub.Item}.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def retract(request):
+        """
+        Called when a item retraction request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with C{None} when the given items have
+                 been retracted.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def purge(request):
+        """
+        Called when a node purge request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with C{None} when the node has been
+                 purged.
+        @rtype: L{defer.Deferred}
+        """
+
+
+    def delete(request):
+        """
+        Called when a node deletion request has been received.
+
+        @param request: The publish-subscribe request.
+        @type request: L{wokkel.pubsub.PubSubRequest}
+        @return: A deferred that fires with C{None} when the node has been
+                 deleted.
+        @rtype: L{defer.Deferred}
+        """
+
 
 
@@ -655 +913 @@
         """
         """
-