89 lines
2.7 KiB
ReStructuredText
89 lines
2.7 KiB
ReStructuredText
.. _internal-api:
|
|
|
|
Internal "API"
|
|
==============
|
|
|
|
Slixmpp has a generic API registry that can be used by its plugins to allow
|
|
access control, redefinition of behaviour, without having to inherit from the
|
|
plugin or do more dark magic.
|
|
|
|
The idea is that each api call can be replaced, most of them use a form
|
|
of in-memory storage that can be, for example, replaced with database
|
|
or file-based storaged.
|
|
|
|
|
|
Each plugin is assigned an API proxy bound to itself, but only a few make use
|
|
of it.
|
|
|
|
See also :ref:`api-simple-tuto`.
|
|
|
|
Description of a generic API call
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
def get_toto(jid, node, ifrom, args):
|
|
return 'toto'
|
|
|
|
self.xmpp.plugin['xep_XXXX'].api.register(handler, 'get_toto')
|
|
|
|
Each API call will receive 4 parameters (which can be ``None`` if data
|
|
is not relevant to the operation), which are ``jid`` (``Optional[JID]``),
|
|
``node`` (``Optional[str]``), ``ifrom`` (``Optional[JID]``), and ``args``
|
|
(``Any``).
|
|
|
|
- ``jid``, if relevant, represents the JID targeted by that operation
|
|
- ``node``, if relevant is an arbitrary string, but was thought for, e.g.,
|
|
a pubsub or disco node.
|
|
- ``ifrom``, if relevant, is the JID the event is coming from.
|
|
- ``args`` is the event-specific data passed on by the plugin, often a dict
|
|
of arguments (can be None as well).
|
|
|
|
.. note::
|
|
Since 1.8.0, API calls can be coroutines.
|
|
|
|
|
|
Handler hierarchy
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
The ``self.api.register()`` signature is as follows:
|
|
|
|
.. code-block:: python
|
|
|
|
def register(handler, op, jid=None, node=None, default=False):
|
|
pass
|
|
|
|
As you can see, :meth:`~.APIRegistry.register` takes an additional ctype
|
|
parameter, but the :class:`~.APIWrapper` takes care of that for us (in most
|
|
cases, it is the name of the XEP plugin, such as ``'xep_0XXX'``).
|
|
|
|
When you register a handler, you register it for an ``op``, for **operation**.
|
|
For example, ``get_vcard``.
|
|
|
|
``handler`` and ``op`` are the only two required parameters (and in many cases,
|
|
all you will ever need). You can, however, go further and register handlers
|
|
for specific values of the ``jid`` and ``node`` parameters of the calls.
|
|
|
|
The priority of the execution of handlers is as follows:
|
|
|
|
- Check if a handler for both values of ``node`` and ``jid`` has been defined
|
|
- If not found, check if a handler for this value of ``jid`` has been defined
|
|
- If not found, check if a handler for this value of ``node`` has been defined
|
|
- If still not found, get the global handler (no parameter registered)
|
|
|
|
|
|
Raw documentation
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
This documentation is provided for reference, but :meth:`~.APIRegistry.register`
|
|
should be all you need.
|
|
|
|
|
|
.. module:: slixmpp.api
|
|
|
|
.. autoclass:: APIRegistry
|
|
:members:
|
|
|
|
.. autoclass:: APIWrapper
|
|
|