1
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
3
<title>Twisted Documentation: Overview of Twisted IM</title>
4
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
8
<h1 class="title">Overview of Twisted IM</h1>
9
<div class="toc"><ol><li><a href="#auto0">Code flow</a></li><ul><li><a href="#auto1">AccountManager</a></li><li><a href="#auto2">ChatUI</a></li><li><a href="#auto3">Conversation and GroupConversation</a></li><li><a href="#auto4">Accounts</a></li></ul></ol></div>
13
<div class="note"><strong>Note: </strong>Twisted IM and Twisted Words are both known to be in a state
14
of flux at the moment. Several of the APIs discussed here have fallen short of
15
their original goals and <em>will</em> be changing within the next few releases
16
of Twisted. The good news is that newer versions will be based on our
17
experiences with the current ones and will provide much more access to features
18
beyond plain-text chat message relaying in different protocols.</div>
20
<p>Twisted IM (Instance Messenger) is a multi-protocol chat
21
framework, based on the Twisted framework we've all come to know
22
and love. It's fairly simple and extensible in two directions -
23
it's pretty easy to add new protocols, and it's also quite easy
24
to add new front-ends.</p>
26
<h2>Code flow<a name="auto0"/></h2>
27
<p>Twisted IM is usually started from the file
28
<code>twisted/scripts/im.py</code> (maybe with a shell-script
29
wrapper or similar). Twisted currently comes with two
30
interfaces for Twisted IM - one written in GTK for Python
31
under Linux, and one written in Swing for Jython.
32
<code>im.py</code> picks an implementation and starts it - if
33
you want to write your own interface, you can modify
34
<code>im.py</code> to start it under appropriate
37
<p>Once started, both interfaces behave in a very similar
38
fashion, so I won't be getting into differences here.</p>
40
<h3>AccountManager<a name="auto1"/></h3>
41
<p>Control flow starts at the relevant subclass of <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.im.baseaccount.AccountManager.html" title="twisted.im.baseaccount.AccountManager">baseaccount.AccountManager</a></code>.
42
The AccountManager is responsible for, well, managing accounts
43
- remembering what accounts are available, their
44
settings, adding and removal of accounts, and making accounts
45
log on at startup.</p>
47
<p>This would be a good place to start your interface, load a
48
list of accounts from disk and tell them to login. Most of the
49
method names in <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.im.baseaccount.AccountManager.html" title="twisted.im.baseaccount.AccountManager">AccountManager</a></code>
50
are pretty self-explanatory, and your subclass can override
51
whatever it wants, but you <em>need</em> to override <code class="python">__init__</code>. Something like
54
<pre class="python"><p class="py-linenumber">1
59
</p><span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>):
60
<span class="py-src-variable">self</span>.<span class="py-src-variable">chatui</span> = ... <span class="py-src-comment"># Your subclass of basechat.ChatUI</span>
61
<span class="py-src-variable">self</span>.<span class="py-src-variable">accounts</span> = ... <span class="py-src-comment"># Load account list</span>
62
<span class="py-src-keyword">for</span> <span class="py-src-variable">a</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">accounts</span>:
63
<span class="py-src-variable">a</span>.<span class="py-src-variable">logOn</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">chatui</span>)
66
<h3>ChatUI<a name="auto2"/></h3>
67
<p>Account objects talk to the user via a subclass of <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.im.basechat.ChatUI.html" title="twisted.im.basechat.ChatUI">basechat.ChatUI</a></code>.
68
This class keeps track of all the various conversations that
69
are currently active, so that when an account receives and
70
incoming message, it can put that message in its correct
73
<p>How much of this class you need to override depends on what
74
you need to do. You will need to override
75
<code>getConversation</code> (a one-on-one conversation, like
76
an IRC DCC chat) and <code>getGroupConversation</code> (a
77
multiple user conversation, like an IRC channel). You might
78
want to override <code>getGroup</code> and
79
<code>getPerson</code>.</p>
81
<p>The main problem with the default versions of the above
82
routines is that they take a parameter, <code>Class</code>,
83
which defaults to an abstract implementation of that class -
84
for example, <code>getConversation</code> has a
85
<code>Class</code> parameter that defaults to <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.im.basechat.Conversation.html" title="twisted.im.basechat.Conversation">basechat.Conversation</a></code> which
86
raises a lot of <code>NotImplementedError</code>s. In your
87
subclass, override the method with a new method whose Class
88
parameter defaults to your own implementation of
89
<code>Conversation</code>, that simply calls the parent
90
class' implementation.</p>
92
<h3>Conversation and GroupConversation<a name="auto3"/></h3>
93
<p>These classes are where your interface meets the chat
94
protocol. Chat protocols get a message, find the appropriate
95
<code>Conversation</code> or <code>GroupConversation</code>
96
object, and call its methods when various interesting things
99
<p>Override whatever methods you want to get the information
100
you want to display. You must override the <code>hide</code>
101
and <code>show</code> methods, however - they are called
102
frequently and the default implementation raises
103
<code>NotImplementedError</code>.</p>
105
<h3>Accounts<a name="auto4"/></h3>
106
<p>An account is an instance of a subclass of <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.im.basesupport.AbstractAccount.html" title="twisted.im.basesupport.AbstractAccount">basesupport.AbstractAccount</a></code>.
107
For more details and sample code, see the various
108
<code>*support</code> files in <code>twisted.im</code>.</p>
112
<p><a href="index.html">Index</a></p>
113
<span class="version">Version: 10.0.0</span>
b'\\ No newline at end of file'