diff options
Diffstat (limited to 'sleekxmpp/plugins/xep_0030/disco.py')
| -rw-r--r-- | sleekxmpp/plugins/xep_0030/disco.py | 366 |
1 files changed, 304 insertions, 62 deletions
diff --git a/sleekxmpp/plugins/xep_0030/disco.py b/sleekxmpp/plugins/xep_0030/disco.py index c323ba7c..ad3d0ae2 100644 --- a/sleekxmpp/plugins/xep_0030/disco.py +++ b/sleekxmpp/plugins/xep_0030/disco.py @@ -26,30 +26,66 @@ class xep_0030(base_plugin): """ XEP-0030: Service Discovery + Service discovery in XMPP allows entities to discover information about + other agents in the network, such as the feature sets supported by a + client, or signposts to other, related entities. + + Also see <http://www.xmpp.org/extensions/xep-0030.html>. + + The XEP-0030 plugin works using a hierarchy of dynamic + node handlers, ranging from global handlers to specific + JID+node handlers. The default set of handlers operate + in a static manner, storing disco information in memory. + However, custom handlers may use any available backend + storage mechanism desired, such as SQLite or Redis. + + Node handler hierarchy: + JID | Node | Level + --------------------- + None | None | Global + Given | None | All nodes for the JID + None | Given | Node on self.xmpp.boundjid + Given | Given | A single node + Stream Handlers: - Disco Info -- - Disco Items -- + Disco Info -- Any Iq stanze that includes a query with the + namespace http://jabber.org/protocol/disco#info. + Disco Items -- Any Iq stanze that includes a query with the + namespace http://jabber.org/protocol/disco#items. Events: - disco_info -- - disco_items -- - disco_info_query -- - disco_items_query -- + disco_info -- Received a disco#info Iq query result. + disco_items -- Received a disco#items Iq query result. + disco_info_query -- Received a disco#info Iq query request. + disco_items_query -- Received a disco#items Iq query request. + + Attributes: + stanza -- A reference to the module containing the stanza classes + provided by this plugin. + static -- Object containing the default set of static node handlers. + xmpp -- The main SleekXMPP object. Methods: - set_node_handler -- - del_node_handler -- - add_identity -- + set_node_handler -- Assign a handler to a JID/node combination. + del_node_handler -- Remove a handler from a JID/node combination. + get_info -- Retrieve disco#info data, locally or remote. + get_items -- Retrieve disco#items data, locally or remote. + set_identities -- + set_features -- + set_items -- + del_items -- del_identity -- - add_feature -- del_feature -- - add_item -- del_item -- - get_info -- - get_items -- + add_identity -- + add_feature -- + add_item -- """ def plugin_init(self): + """ + Start the XEP-0030 plugin. + """ self.xep = '0030' self.description = 'Service Discovery' self.stanza = sleekxmpp.plugins.xep_0030.stanza @@ -70,42 +106,89 @@ class xep_0030(base_plugin): self.static = StaticDisco(self.xmpp) self._disco_ops = ['get_info', 'set_identities', 'set_features', - 'del_info', 'get_items', 'set_items', 'del_items', + 'get_items', 'set_items', 'del_items', 'add_identity', 'del_identity', 'add_feature', 'del_feature', 'add_item', 'del_item'] - self.handlers = {} + self._handlers = {} for op in self._disco_ops: - self.handlers[op] = {'global': getattr(self.static, op), - 'jid': {}, - 'node': {}} - + self._handlers[op] = {'global': getattr(self.static, op), + 'jid': {}, + 'node': {}} def set_node_handler(self, htype, jid=None, node=None, handler=None): """ + Add a node handler for the given hierarchy level and + handler type. + + Node handlers are ordered in a hierarchy where the + most specific handler is executed. Thus, a fallback, + global handler can be used for the majority of cases + with a few node specific handler that override the + global behavior. + + Node handler hierarchy: + JID | Node | Level + --------------------- + None | None | Global + Given | None | All nodes for the JID + None | Given | Node on self.xmpp.boundjid + Given | Given | A single node + + Handler types: + get_info + get_items + set_identities + set_features + set_items + del_items + del_identity + del_feature + del_item + add_identity + add_feature + add_item + Arguments: - htype - jid - node - handler + htype -- The operation provided by the handler. + jid -- The JID the handler applies to. May be narrowed + further if a node is given. + node -- The particular node the handler is for. If no JID + is given, then the self.xmpp.boundjid.full is + assumed. + handler -- The handler function to use. """ if htype not in self._disco_ops: return if jid is None and node is None: - self.handlers[htype]['global'] = handler + self._handlers[htype]['global'] = handler elif node is None: - self.handlers[htype]['jid'][jid] = handler + self._handlers[htype]['jid'][jid] = handler elif jid is None: jid = self.xmpp.boundjid.full - self.handlers[htype]['node'][(jid, node)] = handler + self._handlers[htype]['node'][(jid, node)] = handler else: - self.handlers[htype]['node'][(jid, node)] = handler + self._handlers[htype]['node'][(jid, node)] = handler def del_node_handler(self, htype, jid, node): """ + Remove a handler type for a JID and node combination. + + The next handler in the hierarchy will be used if one + exists. If removing the global handler, make sure that + other handlers exist to process existing nodes. + + Node handler hierarchy: + JID | Node | Level + --------------------- + None | None | Global + Given | None | All nodes for the JID + None | Given | Node on self.xmpp.boundjid + Given | Given | A single node + Arguments: - htype - jid - node + htype -- The type of handler to remove. + jid -- The JID from which to remove the handler. + node -- The node from which to remove the handler. """ self.set_node_handler(htype, jid, node, None) @@ -132,14 +215,28 @@ class xep_0030(base_plugin): def get_info(self, jid=None, node=None, local=False, **kwargs): """ + Retrieve the disco#info results from a given JID/node combination. + + Info may be retrieved from both local resources and remote agents; + the local parameter indicates if the information should be gathered + by executing the local node handlers, or if a disco#info stanza + must be generated and sent. + Arguments: - jid -- - node -- - local -- - dfrom -- - block -- - timeout -- - callback -- + jid -- Request info from this JID. + node -- The particular node to query. + local -- If true, then the query is for a JID/node + combination handled by this Sleek instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remove JID to retrieve the info. + dfrom -- Specifiy the sender's JID. + block -- If true, block and wait for the stanzas' reply. + timeout -- The time in seconds to block while waiting for + a reply. If None, then wait indefinitely. + callback -- Optional callback to execute when a reply is + received instead of blocking and waiting for + the reply. """ if local or jid is None: log.debug("Looking up local disco#info data " + \ @@ -158,14 +255,28 @@ class xep_0030(base_plugin): def get_items(self, jid=None, node=None, local=False, **kwargs): """ + Retrieve the disco#items results from a given JID/node combination. + + Items may be retrieved from both local resources and remote agents; + the local parameter indicates if the items should be gathered by + executing the local node handlers, or if a disco#items stanza must + be generated and sent. + Arguments: - jid -- - node -- - local -- - dfrom -- - block -- - timeout -- - callback -- + jid -- Request info from this JID. + node -- The particular node to query. + local -- If true, then the query is for a JID/node + combination handled by this Sleek instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remove JID to retrieve the items. + dfrom -- Specifiy the sender's JID. + block -- If true, block and wait for the stanzas' reply. + timeout -- The time in seconds to block while waiting for + a reply. If None, then wait indefinitely. + callback -- Optional callback to execute when a reply is + received instead of blocking and waiting for + the reply. """ if local or jid is None: return self._run_node_handler('get_items', jid, node, kwargs) @@ -179,37 +290,169 @@ class xep_0030(base_plugin): block=kwargs.get('block', None), callback=kwargs.get('callback', None)) - def set_info(self, jid=None, node=None, **kwargs): - self._run_node_handler('set_info', jid, node, kwargs) + def set_items(self, jid=None, node=None, **kwargs): + """ + Set or replace all items for the specified JID/node combination. - def del_info(self, jid=None, node=None, **kwargs): - self._run_node_handler('del_info', jid, node, kwargs) + The given items must be in a list or set where each item is a + tuple of the form: (jid, node, name). - def set_items(self, jid=None, node=None, **kwargs): + Arguments: + jid -- The JID to modify. + node -- Optional node to modify. + items -- A series of items in tuple format. + """ self._run_node_handler('set_items', jid, node, kwargs) def del_items(self, jid=None, node=None, **kwargs): + """ + Remove all items from the given JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- Optional node to modify. + """ self._run_node_handler('del_items', jid, node, kwargs) + def add_item(self, jid=None, node=None, **kwargs): + """ + Add a new item element to the given JID/node combination. + + Each item is required to have a JID, but may also specify + a node value to reference non-addressable entities. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + ijid -- The JID for the item. + inode -- Optional node for the item. + name -- Optional name for the item. + """ + self._run_node_handler('add_item', jid, node, kwargs) + + def del_item(self, jid=None, node=None, **kwargs): + """ + Remove a single item from the given JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + ijid -- The item's JID. + inode -- The item's node. + """ + self._run_node_handler('del_item', jid, node, kwargs) + def add_identity(self, jid=None, node=None, **kwargs): + """ + Add a new identity to the given JID/node combination. + + Each identity must be unique in terms of all four identity + components: category, type, name, and language. + + Multiple, identical category/type pairs are allowed only + if the xml:lang values are different. Likewise, multiple + category/type/xml:lang pairs are allowed so long as the + names are different. A category and type is always required. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + category -- The identity's category. + itype -- The identity's type. + name -- Optional name for the identity. + lang -- Optional two-letter language code. + """ self._run_node_handler('add_identity', jid, node, kwargs) def add_feature(self, jid=None, node=None, **kwargs): + """ + Add a feature to a JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + feature -- The namespace of the supported feature. + """ self._run_node_handler('add_feature', jid, node, kwargs) def del_identity(self, jid=None, node=None, **kwargs): + """ + Remove an identity from the given JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + category -- The identity's category. + itype -- The identity's type value. + name -- Optional, human readable name for the identity. + lang -- Optional, the identity's xml:lang value. + """ self._run_node_handler('del_identity', jid, node, kwargs) def del_feature(self, jid=None, node=None, **kwargs): + """ + Remove a feature from a given JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + feature -- The feature's namespace. + """ self._run_node_handler('del_feature', jid, node, kwargs) - def add_item(self, jid=None, node=None, **kwargs): - self._run_node_handler('add_item', jid, node, kwargs) + def set_identities(self, jid=None, node=None, **kwargs): + """ + Add or replace all identities for the given JID/node combination. - def del_item(self, jid=None, node=None, **kwargs): - self._run_node_handler('del_item', jid, node, kwargs) + The identities must be in a set where each identity is a tuple + of the form: (category, type, lang, name) + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + identities -- A set of identities in tuple form. + lang -- Optional, xml:lang value. + """ + self._run_node_handler('set_identities', jid, node, kwargs) - def _run_node_handler(self, htype, jid, node, data=None): + def del_identities(self, jid=None, node=None, **kwargs): + """ + Remove all identities for a JID/node combination. + + If a language is specified, only identities using that + language will be removed. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + lang -- Optional. If given, only remove identities + using this xml:lang value. + """ + self._run_node_handler('del_identities', jid, node, kwargs) + + def set_features(self, jid=None, node=None, **kwargs): + """ + Add or replace the set of supported features + for a JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + features -- The new set of supported features. + """ + self._run_node_handler('set_features', jid, node, kwargs) + + def del_features(self, jid=None, node=None, **kwargs): + """ + Remove all features from a JID/node combination. + + Arguments: + jid -- The JID to modify. + node -- The node to modify. + """ + self._run_node_handler('del_features', jid, node, kwargs) + + def _run_node_handler(self, htype, jid, node, data={}): """ Execute the most specific node handler for the given JID/node combination. @@ -218,19 +461,19 @@ class xep_0030(base_plugin): htype -- The handler type to execute. jid -- The JID requested. node -- The node requested. - dat -- Optional, custom data to pass to the handler. + data -- Optional, custom data to pass to the handler. """ if jid is None: jid = self.xmpp.boundjid.full if node is None: node = '' - if self.handlers[htype]['node'].get((jid, node), False): - return self.handlers[htype]['node'][(jid, node)](jid, node, data) - elif self.handlers[htype]['jid'].get(jid, False): - return self.handlers[htype]['jid'][jid](jid, node, data) - elif self.handlers[htype]['global']: - return self.handlers[htype]['global'](jid, node, data) + if self._handlers[htype]['node'].get((jid, node), False): + return self._handlers[htype]['node'][(jid, node)](jid, node, data) + elif self._handlers[htype]['jid'].get(jid, False): + return self._handlers[htype]['jid'][jid](jid, node, data) + elif self._handlers[htype]['global']: + return self._handlers[htype]['global'](jid, node, data) else: return None @@ -311,4 +554,3 @@ class xep_0030(base_plugin): "Using default disco#info feature.") info.add_feature(info.namespace) return info - |