summaryrefslogtreecommitdiff
path: root/sleekxmpp/plugins/xep_0060/pubsub.py
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-08-26 16:57:37 -0700
committerLance Stout <lancestout@gmail.com>2011-08-26 16:57:37 -0700
commit3fb3f63e5130dff83fe44a94b5849b919baa89ef (patch)
tree050d931396313744d7a365bc00feda87252b1ed3 /sleekxmpp/plugins/xep_0060/pubsub.py
parentd12949ff1cf1a6405d6f430bc8ca77567b7cc9be (diff)
downloadslixmpp-3fb3f63e5130dff83fe44a94b5849b919baa89ef.tar.gz
slixmpp-3fb3f63e5130dff83fe44a94b5849b919baa89ef.tar.bz2
slixmpp-3fb3f63e5130dff83fe44a94b5849b919baa89ef.tar.xz
slixmpp-3fb3f63e5130dff83fe44a94b5849b919baa89ef.zip
Add docs + extended Iq send arguments to pubsub methods.
Diffstat (limited to 'sleekxmpp/plugins/xep_0060/pubsub.py')
-rw-r--r--sleekxmpp/plugins/xep_0060/pubsub.py245
1 files changed, 199 insertions, 46 deletions
diff --git a/sleekxmpp/plugins/xep_0060/pubsub.py b/sleekxmpp/plugins/xep_0060/pubsub.py
index 7d372222..6b981ead 100644
--- a/sleekxmpp/plugins/xep_0060/pubsub.py
+++ b/sleekxmpp/plugins/xep_0060/pubsub.py
@@ -8,6 +8,7 @@
import logging
+from sleekxmpp.xmlstream import JID
from sleekxmpp.plugins.base import base_plugin
from sleekxmpp.plugins.xep_0060 import stanza
@@ -79,63 +80,197 @@ class xep_0060(base_plugin):
return iq.send(block=block, callback=callback, timeout=timeout)
- def subscribe(self, jid, node, bare=True, subscribee=None):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ def subscribe(self, jid, node, bare=True, subscribee=None, ifrom=None,
+ block=True, callback=None, timeout=None):
+ """
+ Subscribe to updates from a pubsub node.
+
+ The rules for determining the JID that is subscribing to the node are:
+ 1. If subscribee is given, use that as provided.
+ 2. If ifrom was given, use the bare or full version based on bare.
+ 3. Otherwise, use self.xmpp.boundjid based on bare.
+
+ Arguments:
+ jid -- The pubsub service JID.
+ node -- The node to subscribe to.
+ bare -- Indicates if the subscribee is a bare or full JID.
+ Defaults to True for a bare JID.
+ subscribee -- The JID that is subscribing to the node.
+ ifrom -- Specify the sender's JID.
+ block -- Specify if the send call will block until a response
+ is received, or a timeout occurs. Defaults to True.
+ timeout -- The length of time (in seconds) to wait for a response
+ before exiting the send call if blocking is used.
+ Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+ callback -- Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
+ """
+ iq = self.xmpp.Iq(sto=jid, stype='set')
iq['pubsub']['subscribe']['node'] = node
+ if ifrom:
+ iq['from'] = ifrom
+
if subscribee is None:
- if bare:
- iq['pubsub']['subscribe']['jid'] = self.xmpp.boundjid.bare
+ if ifrom:
+ if bare:
+ subscribee = JID(ifrom).bare
+ else:
+ subscribee = ifrom
else:
- iq['pubsub']['subscribe']['jid'] = self.xmpp.boundjid.full
- else:
- iq['pubsub']['subscribe']['jid'] = subscribee
- return iq.send()
+ if bare:
+ subscribee = self.xmpp.boundjid.bare
+ else:
+ subscribee = self.xmpp.boundjid
- def unsubscribe(self, jid, node, subid=None, bare=True, subscribee=None):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ iq['pubsub']['subscribe']['jid'] = subscribee
+ return iq.send(block=block, callback=callback, timeout=timeout)
+
+ def unsubscribe(self, jid, node, subid=None, bare=True, subscribee=None,
+ ifrom=None, block=True, callback=None, timeout=None):
+ """
+ Unubscribe from updates from a pubsub node.
+
+ The rules for determining the JID that is unsubscribing
+ from the node are:
+ 1. If subscribee is given, use that as provided.
+ 2. If ifrom was given, use the bare or full version based on bare.
+ 3. Otherwise, use self.xmpp.boundjid based on bare.
+
+ Arguments:
+ jid -- The pubsub service JID.
+ node -- The node to subscribe to.
+ subid -- The specific subscription, if multiple subscriptions
+ exist for this JID/node combination.
+ bare -- Indicates if the subscribee is a bare or full JID.
+ Defaults to True for a bare JID.
+ subscribee -- The JID that is subscribing to the node.
+ ifrom -- Specify the sender's JID.
+ block -- Specify if the send call will block until a response
+ is received, or a timeout occurs. Defaults to True.
+ timeout -- The length of time (in seconds) to wait for a response
+ before exiting the send call if blocking is used.
+ Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+ callback -- Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
+ """
+ iq = self.xmpp.Iq(sto=jid, stype='set')
iq['pubsub']['unsubscribe']['node'] = node
+ if ifrom:
+ iq['from'] = ifrom
+
if subscribee is None:
- if bare:
- iq['pubsub']['unsubscribe']['jid'] = self.xmpp.boundjid.bare
+ if ifrom:
+ if bare:
+ subscribee = JID(ifrom).bare
+ else:
+ subscribee = ifrom
else:
- iq['pubsub']['unsubscribe']['jid'] = self.xmpp.boundjid.full
- else:
- iq['pubsub']['unsubscribe']['jid'] = subscribee
- if subid is not None:
- iq['pubsub']['unsubscribe']['subid'] = subid
- return iq.send()
+ if bare:
+ subscribee = self.xmpp.boundjid.bare
+ else:
+ subscribee = self.xmpp.boundjid
+
+ iq['pubsub']['unsubscribe']['jid'] = subscribee
+ iq['pubsub']['unsubscribe']['subid'] = subid
+ return iq.send(block=block, callback=callback, timeout=timeout)
+
+ def get_node_config(self, jid, node=None, ifrom=None, block=None,
+ callback=None, timeout=None):
+ """
+ Retrieve the configuration for a node, or the pubsub service's
+ default configuration for new nodes.
- def get_node_config(self, jid, node=None): # if no node, then grab default
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='get')
+ Arguments:
+ jid -- The JID of the pubsub service.
+ node -- The node to retrieve the configuration for. If None,
+ the default configuration for new nodes will be
+ requested. Defaults to None.
+ ifrom -- Specify the sender's JID.
+ block -- Specify if the send call will block until a response
+ is received, or a timeout occurs. Defaults to True.
+ timeout -- The length of time (in seconds) to wait for a response
+ before exiting the send call if blocking is used.
+ Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+ callback -- Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
+ """
+ iq = self.xmpp.Iq(sto=jid, stype='get')
+ if ifrom:
+ iq['from'] = ifrom
if node is None:
iq['pubsub_owner']['default']
else:
iq['pubsub_owner']['configure']['node'] = node
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
+
+ def get_node_subscriptions(self, jid, node, ifrom=None, block=True,
+ callback=None, timeout=None):
+ """
+ Retrieve the subscriptions associated with a given node.
- def get_node_subscriptions(self, jid, node):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='get')
+ Arguments:
+ jid -- The JID of the pubsub service.
+ node -- The node to retrieve subscriptions from.
+ ifrom -- Specify the sender's JID.
+ block -- Specify if the send call will block until a response
+ is received, or a timeout occurs. Defaults to True.
+ timeout -- The length of time (in seconds) to wait for a response
+ before exiting the send call if blocking is used.
+ Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+ callback -- Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
+ """
+ iq = self.xmpp.Iq(sto=jid, stype='get')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub_owner']['subscriptions']['node'] = node
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def get_node_affiliations(self, jid, node):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='get')
+ def get_node_affiliations(self, jid, node, ifrom=None, block=True,
+ callback=None, timeout=None):
+ """
+ Retrieve the affiliations associated with a given node.
+
+ Arguments:
+ jid -- The JID of the pubsub service.
+ node -- The node to retrieve affiliations from.
+ ifrom -- Specify the sender's JID.
+ block -- Specify if the send call will block until a response
+ is received, or a timeout occurs. Defaults to True.
+ timeout -- The length of time (in seconds) to wait for a response
+ before exiting the send call if blocking is used.
+ Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+ callback -- Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
+ """
+ iq = self.xmpp.Iq(sto=jid, stype='get')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub_owner']['affiliations']['node'] = node
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def delete_node(self, jid, node):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='get')
+ def delete_node(self, jid, node, ifrom=None, block=True,
+ callback=None, timeout=None):
+ iq = self.xmpp.Iq(sto=jid, stype='get')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub_owner']['delete']['node'] = node
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def set_node_config(self, jid, node, config):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ def set_node_config(self, jid, node, config, ifrom=None, block=True,
+ callback=None, timeout=None):
+ iq = self.xmpp.Iq(sto=jid, stype='set')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub_owner']['configure']['node'] = node
iq['pubsub_owner']['configure']['config'] = config
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def publish(self, jid, node, items=[]):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ def publish(self, jid, node, items=[], ifrom=None, block=True,
+ callback=None, timeout=None):
+ iq = self.xmpp.Iq(sto=jid, stype='set')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub']['publish']['node'] = node
for id, payload in items:
item = stanza.pubsub.Item()
@@ -143,24 +278,42 @@ class xep_0060(base_plugin):
item['id'] = id
item['payload'] = payload
iq['pubsub']['publish'].append(item)
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def retract(self, jid, node, item):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ def retract(self, jid, node, item, ifrom=None, block=True,
+ callback=None, timeout=None):
+ iq = self.xmpp.Iq(sto=jid, stype='set')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub']['retract']['node'] = node
item = stanza.pubsub.Item()
item['id'] = item
iq['pubsub']['retract'].append(item)
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)
- def get_nodes(self, jid):
- return self.xmpp.plugin['xep_0030'].get_items(jid)
+ def get_nodes(self, jid, ifrom=None, block=True,
+ callback=None, timeout=None, iterator=False):
+ return self.xmpp.plugin['xep_0030'].get_items(jid, ifrom=ifrom,
+ block=block,
+ callback=callback,
+ timeout=timeout,
+ iterator=iterator)
- def getItems(self, jid, node):
- return self.xmpp.plugin['xep_0030'].get_items(jid, node)
+ def get_items(self, jid, node, ifrom=None, block=True,
+ callback=None, timeout=None, iterator=False):
+ return self.xmpp.plugin['xep_0030'].get_items(jid, node,
+ ifrom=ifrom,
+ block=block,
+ callback=callback,
+ timeout=timeout,
+ iterator=iterator)
- def modify_affiliation(self, jid, node, affiliation, user_jid=None):
- iq = self.xmpp.Iq(sto=jid, sfrom=self.xmpp.boundjid, stype='set')
+ def modify_affiliation(self, jid, node, affiliation, user_jid=None,
+ ifrom=None, block=True, callback=None,
+ timeout=None):
+ iq = self.xmpp.Iq(sto=jid, stype='set')
+ if ifrom:
+ iq['from'] = ifrom
iq['pubsub_owner']['affiliations']
aff = stanza.pubsub.Affiliation()
aff['node'] = node
@@ -168,4 +321,4 @@ class xep_0060(base_plugin):
aff['jid'] = user_jid
aff['affiliation'] = affiliation
iq['pubsub_owner']['affiliations'].append(aff)
- return iq.send()
+ return iq.send(block=block, callback=callback, timeout=timeout)