source: doc/client.rst @ 251:554782284e08

Last change on this file since 251:554782284e08 was 170:bb143a4ae70d, checked in by Ralph Meijer <ralphm@…>, 10 years ago

Add documentation using Sphinx and pydoctor, automate doc generation.

File size: 5.1 KB
RevLine 
[170]1XMPP Clients
2============
3
4Wokkel supports two different approaches to create XMPP client applications,
5one for persistent connections and one for one-off purposes. This builds
6further on the XMPP client functionality that is provided by Twisted Words,
7while providing support for so-called :term:`subprotocols`.
8
9Persistent Clients
10------------------
11
12Persistent clients are meant to be used for extended periods, where the
13application wants to exchange communications with other entities. Instances of
14:api:`wokkel.client.XMPPClient <XMPPClient>` are Twisted services that connect
15to an XMPP server and act as a stream manager that can be assigned as the
16parent of subprotocol implementations.
17
18Basic XMPP client
19^^^^^^^^^^^^^^^^^
20
21The following example creates the most basic XMPP client as a `Twisted
22Application
23<http://twistedmatrix.com/projects/core/documentation/howto/application.html>`_.
24
25.. literalinclude:: listings/client/client1.tac
26   :language: python
27   :linenos:
28
29First we create the application object, to later add services to. The XMPP
30client service is passed a ``JID`` instance and the associated password as
31login credentials to the server. This assumes that the server is set up
32properly, so that the client can connect to the server by extracting the domain
33name from the JID and retrieving the server's address by resolving it through
34DNS (optionally by using SRV records). To see what is exchanged between the
35client and server, we enable traffic logging. Finally, we set the application
36object as the parent of the XMPP client service. This ensures that the service
37gets started properly.
38
39The client can be started with the command ``twistd -noy client.tac``. The
40application will start while logging to the terminal it was started from,
41including the traffic log we enabled. The final lines should look similar to
42this for a regular XMPP server::
43
44    ...
45    2008-02-29 14:21:08+0100 [XmlStream,client] SEND: "<iq type='set' id='H_1'><session xmlns='urn:ietf:params:xml:ns:xmpp-session'/></iq>"
46    2008-02-29 14:21:08+0100 [XmlStream,client] RECV: '<iq type="result" id="H_1" to="test@example.org/ca05ba89"><session xmlns="urn:ietf:params:xml:ns:xmpp-session"/></iq>'
47
48This client does not do much beyond logging into the server, and we can shut it
49down by pressing ``CTRL-C``.
50
51Adding a subprotocol handler
52^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54The next step is to add a subprotocol handler to the client, the presence
55handler:
56
57.. literalinclude:: listings/client/client2.tac
58   :language: python
59   :linenos:
60
61The :api:`wokkel.xmppim.PresenceProtocol <PresenceProtocol>` instance has a
62number of methods for sending presence, but can also be subclassed to process
63incoming presence from contacts. For now we just add the handler to our client
64by setting the handler's parent to the client service. Then we ask it to send
65available presence. Although we are not connected at this point yet, the
66corresponding message will be stored by the client service and sent as soon as
67we have successfully connected and authenticated.
68
69One-off clients
70---------------
71
72Sometimes, you just want a client that logs in, do a short task, log out again
73and stop the application. For this, wokkel has the
74:api:`wokkel.client.DeferredClientFactory <DeferredClientFactory>`. As the name
75suggests, it is based on working with deferreds. In the following example we
76create a subprotocol handler for inquiring a server for what software and the
77version it is running.
78
79.. literalinclude:: listings/client/one_off_client.tac
80   :language: python
81   :linenos:
82
83In this example we dive a little deeper in the XMPP protocol handling. Instead
84of using the more polished :api:`wokkel.client.XMPPClient <XMPPClient>`, we
85create a protocol factory that is responsible for handling the protocol once a
86connection has been made, including logging in and setting up a stream manager.
87The :api:`wokkel.client.clientFactory <clientFactory>` however is responsible
88for establishing the connection. When it does, and the connection has been
89initialized (which includes authentication), the returned deferred will be
90fired. In case of a connection or initialization error, the deferred will have
91its errback called instead.
92
93We can now use this deferred to add callbacks for our one-time tasks. The first
94callback we add is ``getVersion``, while using a lambda construct to ignore the
95result of the callback. We pass the object that represents the XML stream, as
96stored in the factory's stream manager. This is needed for tracking the
97response to the version query. The second parameter is the JID that we want to
98send the version request to, in this case, the server that holds the account we
99login with.
100
101The second callback uses the result from the version request, a dictionary with
102the keys ``name`` and ``version`` to hold the software name and version strings
103as reported by our server. Having been passed this dictionary, ``printVersion``
104prints the information to the terminal. The third callback neatly closes the
105stream. In case of any error, the added errback handler just logs it and
106finally we add a callback that is always called, shutting down the application
107after one second.
Note: See TracBrowser for help on using the repository browser.