dreamIRC initial check-in
[enigma2-plugins.git] / dreamirc / src / interfaces.py
1 # -*- Python -*-
2 """Pan-protocol chat client.
3
4 Stability: incendiary, work in progress.
5 """
6 from zope.interface import Interface
7
8 import locals
9 #from locals import *
10 #from twisted.words.im import locals
11
12 # (Random musings, may not reflect on current state of code:)
13 #
14 # Accounts have Protocol components (clients)
15 # Persons have Conversation components
16 # Groups have GroupConversation components
17 # Persons and Groups are associated with specific Accounts
18 # At run-time, Clients/Accounts are slaved to a User Interface
19 #   (Note: User may be a bot, so don't assume all UIs are built on gui toolkits)
20
21
22 class IAccount(Interface):
23     """I represent a user's account with a chat service.
24
25     @cvar gatewayType: Identifies the protocol used by this account.
26     @type gatewayType: string
27
28     @ivar client: The Client currently connecting to this account, if any.
29     @type client: L{IClient}
30     """
31
32     def __init__(accountName, autoLogin, username, password, host, port):
33         """
34         @type accountName: string
35         @param accountName: A name to refer to the account by locally.
36         @type autoLogin: boolean
37         @type username: string
38         @type password: string
39         @type host: string
40         @type port: integer
41         """
42
43     def isOnline():
44         """Am I online?
45
46         @returntype: boolean
47         """
48
49     def logOn(chatui):
50         """Go on-line.
51
52         @type chatui: Implementor of C{IChatUI}
53
54         @returntype: Deferred L{Client}
55         """
56
57     def logOff():
58         """Sign off.
59         """
60
61     def getGroup(groupName):
62         """
63         @returntype: L{Group<IGroup>}
64         """
65
66     def getPerson(personName):
67         """
68         @returntype: L{Person<IPerson>}
69         """
70
71 class IClient(Interface):
72     """
73     @ivar account: The Account I am a Client for.
74     @type account: L{IAccount}
75     """
76     def __init__(account, chatui, logonDeferred):
77         """
78         @type account: L{IAccount}
79         @type chatui: L{IChatUI}
80         @param logonDeferred: Will be called back once I am logged on.
81         @type logonDeferred: L{Deferred<twisted.internet.defer.Deferred>}
82         """
83
84     def joinGroup(groupName):
85         """
86         @param groupName: The name of the group to join.
87         @type groupName: string
88         """
89
90     def leaveGroup(groupName):
91         """
92         @param groupName: The name of the group to leave.
93         @type groupName: string
94         """
95
96     def getGroupConversation(name,hide=0):
97         pass
98
99     def getPerson(name):
100         pass
101
102
103 class IPerson(Interface):
104     def __init__(name, account):
105         """Initialize me.
106
107         @param name: My name, as the server knows me.
108         @type name: string
109         @param account: The account I am accessed through.
110         @type account: I{Account}
111         """
112
113     def isOnline():
114         """Am I online right now?
115
116         @returntype: boolean
117         """
118
119     def getStatus():
120         """What is my on-line status?
121
122         @returns: L{locals.StatusEnum}
123         """
124
125     def getIdleTime():
126         """
127         @returntype: string (XXX: How about a scalar?)
128         """
129
130     def sendMessage(text, metadata=None):
131         """Send a message to this person.
132
133         @type text: string
134         @type metadata: dict
135         """
136
137
138 class IGroup(Interface):
139     """A group which you may have a conversation with.
140
141     Groups generally have a loosely-defined set of members, who may
142     leave and join at any time.
143
144     @ivar name: My name, as the server knows me.
145     @type name: string
146     @ivar account: The account I am accessed through.
147     @type account: I{Account<IAccount>}
148     """
149
150     def __init__(name, account):
151         """Initialize me.
152
153         @param name: My name, as the server knows me.
154         @type name: string
155         @param account: The account I am accessed through.
156         @type account: I{Account<IAccount>}
157         """
158
159     def setTopic(text):
160         """Set this Groups topic on the server.
161
162         @type text: string
163         """
164
165     def sendGroupMessage(text, metadata=None):
166         """Send a message to this group.
167
168         @type text: string
169
170         @type metadata: dict
171         @param metadata: Valid keys for this dictionary include:
172
173             - C{'style'}: associated with one of:
174                 - C{'emote'}: indicates this is an action
175         """
176
177     def join():
178         pass
179
180     def leave():
181         """Depart this group"""
182
183
184 class IConversation(Interface):
185     """A conversation with a specific person."""
186     def __init__(person, chatui):
187         """
188         @type person: L{IPerson}
189         """
190
191     def show():
192         """doesn't seem like it belongs in this interface."""
193
194     def hide():
195         """nor this neither."""
196
197     def sendText(text, metadata):
198         pass
199
200     def showMessage(text, metadata):
201         pass
202
203     def changedNick(person, newnick):
204         """
205         @param person: XXX Shouldn't this always be Conversation.person?
206         """
207
208 class IGroupConversation(Interface):
209     def show():
210         """doesn't seem like it belongs in this interface."""
211
212     def hide():
213         """nor this neither."""
214
215     def sendText(text, metadata):
216         pass
217
218     def showGroupMessage(sender, text, metadata):
219         pass
220
221     def setGroupMembers(members):
222         """Sets the list of members in the group and displays it to the user
223         """
224
225     def setTopic(topic, author):
226         """Displays the topic (from the server) for the group conversation window
227
228         @type topic: string
229         @type author: string (XXX: Not Person?)
230         """
231
232     def memberJoined(member):
233         """Adds the given member to the list of members in the group conversation
234         and displays this to the user
235
236         @type member: string (XXX: Not Person?)
237         """
238
239     def memberChangedNick(oldnick, newnick):
240         """Changes the oldnick in the list of members to newnick and displays this
241         change to the user
242
243         @type oldnick: string (XXX: Not Person?)
244         @type newnick: string
245         """
246
247     def memberLeft(member):
248         """Deletes the given member from the list of members in the group
249         conversation and displays the change to the user
250
251         @type member: string (XXX: Not Person?)
252         """
253
254
255 class IChatUI(Interface):
256     def registerAccountClient(client):
257         """Notifies user that an account has been signed on to.
258
259         @type client: L{Client<IClient>}
260         """
261
262     def unregisterAccountClient(client):
263         """Notifies user that an account has been signed off or disconnected
264
265         @type client: L{Client<IClient>}
266         """
267
268     def getContactsList():
269         """
270         @returntype: L{ContactsList}
271         """
272
273     # WARNING: You'll want to be polymorphed into something with
274     # intrinsic stoning resistance before continuing.
275
276     def getConversation(person, Class, stayHidden=0):
277         """For the given person object, returns the conversation window
278         or creates and returns a new conversation window if one does not exist.
279
280         @type person: L{Person<IPerson>}
281         @type Class: L{Conversation<IConversation>} class
282         @type stayHidden: boolean
283
284         @returntype: L{Conversation<IConversation>}
285         """
286
287     def getGroupConversation(group,Class,stayHidden=0):
288         """For the given group object, returns the group conversation window or
289         creates and returns a new group conversation window if it doesn't exist.
290
291         @type group: L{Group<interfaces.IGroup>}
292         @type Class: L{Conversation<interfaces.IConversation>} class
293         @type stayHidden: boolean
294
295         @returntype: L{GroupConversation<interfaces.IGroupConversation>}
296         """
297
298     def getPerson(name, client):
299         """Get a Person for a client.
300
301         Duplicates L{IAccount.getPerson}.
302
303         @type name: string
304         @type client: L{Client<IClient>}
305
306         @returntype: L{Person<IPerson>}
307         """
308
309     def getGroup(name, client):
310         """Get a Group for a client.
311
312         Duplicates L{IAccount.getGroup}.
313
314         @type name: string
315         @type client: L{Client<IClient>}
316
317         @returntype: L{Group<IGroup>}
318         """
319
320     def contactChangedNick(oldnick, newnick):
321         """For the given person, changes the person's name to newnick, and
322         tells the contact list and any conversation windows with that person
323         to change as well.
324
325         @type oldnick: string
326         @type newnick: string
327         """