summaryrefslogtreecommitdiffstats
path: root/interfaces/kimproxy/interface/kimiface.h
blob: f3212df6d70341bc1adf333469d4f22631956947 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
/*
    kimiface.h - KDE Instant Messenger DCOP Interface

    Copyright (c) 2004-5 Will Stephenson   <lists@stevello.free-online.co.uk>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/

#ifndef KIMIFACE_H
#define KIMIFACE_H

#include <tqpixmap.h>
#include <dcopobject.h>
#include <tqstringlist.h>
#include <kurl.h>

/**
 * @brief Generic DCOP interface for KDE instant messenger applications
 *
 * The interface has two parts:
 * - methods to get information about IM-contacts, such as their reachability
 *   or their presence status (if the are online or away, etc)
 * - methods to initiate communication with IM-contacts, e.g. sending messages
 *
 * @note If you are looking for a information about accessing application's
 * that implement this interface, have a look at the KIMProxy class.
 *
 * Contacts are identified using unique identifier strings (UID) used by
 * KABC, the KDE address book library.
 * The UID generation is handled by KABC::Addressee so the your application
 * will either have to access the address book or provide a possibility
 * for associating a contact of your application with an entry of the address
 * book.
 *
 * @note one omission of this interface is the lack of control over the range
 * of values used for protocols' names.
 *
 * If you are implementing this interface, note that your application must
 * have the following information in its desktop file, so that it can be
 * identified as providing KIMIface at runtime:
 * @code
 * X-DCOP-ServiceName=<application-name>
 * ServiceTypes=DCOP/InstantMessenger
 * @endcode
 * and the class implementing KIMIface must pass "KIMIface" to the DCOPObject constructor:
 * @code
 * // just need TQObject inheritance and Q_OBJECT if you want signals and slots
 * // no need to use K_DCOP macro again
 *
 * class MyIMIface : public TQObject, public KIMIface
 * {
 *     Q_OBJECT
 * public:
 *    MyIMIface(TQObject* parent = 0, const char* name) :
 *        DCOPObject("KIMIface"), // <-- passing the interface name as required
 *        TQObject(parent, name) {}
 * };
 * @endcode
 *
 * The DCOP part of the interface needs to be processed by the DCOP IDL
 * compiler. The KDE autotools framework will do this automatically, all
 * you have to do is add kimiface.skel and kimiface.stub to the
 * @c SOURCES list in your @c Makefile.am
 *
 * @see KIMProxy
 * @see KABC::AddressBook
 * @see KABC::Addressee
 *
 * @since 3.3
 * @author Will Stephenson <lists@stevello.free-online.co.uk>
 */
class KIMIface : virtual public DCOPObject
{
	K_DCOP

k_dcop:
// ACCESSORS
// contact list
	/**
	 * @brief Obtain a list of IM-contacts that are known to the application
	 *
	 * Return a list of KABC UIDs of all the contacts you have such IDs for.
	 *
	 * @return a list of KABC UIDs known to the application
	 *
	 * @see reachableContacts()
	 * @see onlineContacts()
	 * @see fileTransferContacts()
	 * @see isPresent()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQStringList allContacts() = 0;

	/**
	 * @brief Obtain a list of IM-contacts that are currently reachable
	 *
	 * Return a list of KABC UIDs of the contacts that are reachable in the
	 * sense that you are connected to the IM-service they are
	 * associated with.
	 *
	 * For example if your application supports ICQ and AIM and the ICQ account is
	 * active but the AIM account isn't, return just the ICQ contacts.
	 *
	 * @return a list of KABC UIDs who can receive a message, even if offline
	 *
	 * @see allContacts()
	 * @see onlineContacts()
	 * @see fileTransferContacts()
	 * @see messageContact()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQStringList reachableContacts() = 0;

	/**
	 * @brief Obtain a list of IM-contacts that are currently online
	 *
	 * Return a list of KABC UIDs of the contacts you have any presence
	 * information for that indicates that they are connected to the
	 * IM-service they are associated with.
	 *
	 * @return a list of KABC UIDs who are online with unspecified presence
	 *
	 * @see allContacts()
	 * @see reachableContacts()
	 * @see fileTransferContacts()
	 * @see messageContact()
	 * @see chatWithContact()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQStringList onlineContacts() = 0;

	/**
	 * @brief Obtain a list of IM-contacts who may receive file transfers
	 *
	 * Return a list of KABC UIDs of the contacts that are capable of
	 * receiving file transfers based on the IM-service they are associated
	 * with, i.e. if it is technically able to provide this, on their online
	 * state, i.e. can likely not receive files while offline, and perhaps even
	 * information your application has additionally, e.g. a user config that
	 * tells you that the contact is behind a firewall.
	 *
	 * The simplest implementation is to return the same list as
	 * onlineContacts(), provided all the IM-services that are currently used
	 * support it.
	 *
	 * @return a list of KABC UIDs capable of file transfer
	 *
	 * @see allContacts()
	 * @see reachableContacts()
	 * @see onlineContacts()
	 * @see canReceiveFiles()
	 * @see sendFile()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQStringList fileTransferContacts() = 0;

// individual
	/**
	 * @brief Confirm if a given contact is known to the IM application
	 *
	 * Check if you can map the given KABC UID to one if the IM-contacts, e.g.
	 * the would be part of the list returned by allContacts()
	 *
	 * @param uid the KABC UID you are interested in
	 * @return whether the program knows of this KABC UID
	 *
	 * @see allContacts()
	 * @see presenceString()
	 * @see presenceStatus()
	 * @see KABC::Addressee::uid()
	 */
	virtual bool isPresent( const TQString & uid ) = 0;

	/**
	 * @brief Obtain the IM app's idea of the contact's display name
	 *
	 * Useful if KABC lookups may be too slow. Should return whatever
	 * the application uses in its contact list or similar GUI, e.g.
	 * a nick name, a user configured name string, etc.
	 *
	 * @param uid the KABC UID you are interested in
	 * @return the corresponding display name or TQString:null if the
	 *         UID is unknown
	 *
	 * @see isPresent()
	 * @see presenceString()
	 * @see presenceStatus()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQString displayName( const TQString & uid ) = 0;

	/**
	 * @brief Obtain the IM presence as a i18ned string for the specified
	 *        contact
	 *
	 * Return a translated string your application would use when displaying
	 * the contact's presence, e.g. i18n("Online"), i18n("Away")
	 *
	 * @param uid the KABC UID you want the presence for
	 * @return the i18ned string describing the contact's presence or
	 *         TQString::null if the UID is unknown
	 *
	 * @see isPresent()
	 * @see presenceStatus()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQString presenceString( const TQString & uid ) = 0;

	/**
	 * @brief Obtain the IM presence as a number for the specified contact
	 *
	 * Return one of the following values depending on the given contact's
	 * presence:
	 * - 0 - @c Unknown: for contacts where you can not use any of the other
	 *   values
	 *
	 * - 1 - @c Offline: for contacts that are offline, i.e. not connected to
	 *   their IM-service. If the application itself or the IM-service for the
	 *   given contact is offline return @c Unknown instead
	 *
	 * - 2 - @c Connecting
	 *
	 * - 3 - @c Away: for contacts that are connected to their IM-service but
	 *   not @c Online
	 *
	 * - 4 - @c Online
	 *
	 * @param uid the KABC UID you want the presence for
	 * @return a numeric representation of presence - currently one of
	 *         0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online).
	 *         Returns 0 if the given UID is unknown
	 *
	 * @see isPresent()
	 * @see presenceString()
	 * @see KABC::Addressee::uid()
	 */
	virtual int presenceStatus( const TQString & uid ) = 0;

	/**
	 * @brief Indicate if a given contact can receive files
	 *
	 * @param uid the KABC UID you want to the file transfer capability for
	 * @return whether the specified contact can receive files
	 *
	 * @see fileTransferContacts()
	 * @see KABC::Addressee::uid()
	 */
	virtual bool canReceiveFiles( const TQString & uid ) = 0;

	/**
	 * @brief Indicate if a given contact will be able to respond
	 *
	 * Some media are unidirectional (e.g., sending SMS via a web interface).
	 * This refers to the contact's ability to respond as defined by the
	 * medium, not by their presence.
	 *
	 * Someone may appear offline (SMS has no presence) to you but in fact be
	 * able to respond.
	 *
	 * @param uid the KABC UID you are interested in
	 * @return whether the specified contact can respond
	 *
	 * @see isPresent()
	 * @see KABC::Addressee::uid()
	 */
	virtual bool canRespond( const TQString & uid ) = 0;

	/**
	 * @brief Obtain the KABC UID corresponding to the given IM address
	 *
	 * @param contactId the protocol specific identifier for the contact,
	 *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
	 * @param protocol the IM protocol/service to check. See protocols()
	 * @return the KABC UID for the given contact or @c TQString::null if not
	 *         found or either input stream was empty or the protocol is not
	 *         supported
	 *
	 * @see protocols()
	 * @see addContact()
	 * @see isPresent()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQString locate( const TQString & contactId, const TQString & protocol ) = 0;

// metadata
	/**
	 * @brief Obtain the icon representing the IM presence for the specified
	 *        contact
	 *
	 * Return the image the application would use to display a contact's presence.
	 * The size and other properties of the image are currently unspecified.
	 *
	 * @param uid the KABC UID you want the presence icon for
	 * @return a pixmap representing the contact's presence or a null pixmap
	 *         if the contact is unknown. See TQPixmap::isNull()
	 *
	 * @see isPresent()
	 * @see presenceString()
	 * @see presenceStatus()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQPixmap icon( const TQString & uid ) = 0;

	/**
	 * @brief Obtain the given contact's current context (home, work, or any)
	 *
	 * Not all IM services/protocols support the concept of contexts. If the
	 * given UID maps to such a service, just return @c TQString::null
	 *
	 * @param uid the KABC UID you want the context for
	 * @return a string describing the context, or @c TQString::null if not
	 *         supported or if the contact is unknown
	 *
	 * @see isPresent()
	 * @see KABC::Addressee::uid()
	 */
	virtual TQString context( const TQString & uid ) = 0;

// App capabilities
	/**
	 * @brief Obtain a list of supported IM services/protocols
	 *
	 * Protocol names are currently of the form "protocol name" + "Protocol"
	 * for example:
	 * - AIMProtocol: AOL instant messenger protocol
	 * - MSNProtocol: Microsoft messanger protocol
	 * - ICQProtocol: AOL (Mirabilis) ICQ protocol
	 * - ....
	 *
	 * The string is currently just an identifier to use with methods such as
	 * locate(), addContact() or messageNewContact()
	 *
	 * @return the set of protocols that the application supports
	 *
	 * @see locate()
	 * @see addContact()
	 * @see messageNewContact
	 */
	virtual TQStringList protocols() = 0;

// ACTORS
	/**
	 * @brief Send a single message to the specified contact
	 *
	 * Any response will be handled by the IM client as a normal
	 * conversation.
	 *
	 * Implementations might send the message silently, ask the user for
	 * permission or just prefill the usual message input GUI.
	 *
	 * @note As sending any text could potentially be a breach of the user's
	 * privacy it is recommended to let the user know about it.
	 *
	 * @param uid the KABC UID you want to send the message to
	 * @param message the message text to send to the contact
	 *
	 * @see messageNewContact()
	 * @see chatWithContact()
	 * @see sendFile()
	 * @see isPresent()
	 * @see reachableContacts()
	 * @see KABC::Addressee::uid()
	 */
	virtual void messageContact( const TQString &uid, const TQString& message ) = 0;

	/**
	 * @brief Send a single message to a contact given only its protocol
	 *        specific identifier
	 *
	 * This could be used to send a message without having to know the KABC UID
	 * of the contact or without having to add it first.
	 * 
	 * @param contactId the protocol specific identifier for the contact,
	 *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
	 * @param protocol the IM protocol/service to check. See protocols()
	 *
	 * @see messageContact()
	 * @see chatWithContact()
	 * @see sendFile()
	 * @see locate()
	 * @see protocols()
	 * @see addContact()
	 */
	virtual void messageNewContact( const TQString &contactId, const TQString &protocol ) = 0;

	/**
	 * @brief Start a chat session with the specified contact
	 *
	 * Applications that do not support a chat mode or when the IM-service
	 * of the given contact does not support it, this can also open
	 * a normal message input GUI.
	 *
	 * @param uid the KABC UID you want to chat with
	 *
	 * @see messageContact()
	 * @see messageNewContact()
	 * @see sendFile()
	 * @see isPresent()
	 * @see reachableContacts()
	 * @see KABC::Addressee::uid()
	 */
	virtual void chatWithContact( const TQString &uid ) = 0;

	/**
	 * @brief Send a file to the contact
	 *
	 * Initiates a file transfer with the given contact if possible.
	 *
	 * Implementations might start the transfer right away, ask the user's
	 * permission or just prefill the usual file transfer GUI.
	 *
	 * @note As sending any file could potentially be a breach of the user's
	 * privacy it is recommended to let the user know about it.
	 *
	 * @param uid the KABC UID you want to send to
	 * @param sourceURL a KURL pointing to the file to send
	 * @param altFileName an alternate filename describing the file or a
	 *        description or title
	 * @param fileSize file size in bytes
	 *
	 * @see messageContact()
	 * @see messageNewContact()
	 * @see chatWithContact()
	 * @see isPresent()
	 * @see fileTransferContacts()
	 * @see KABC::Addressee::uid()
	 */
	virtual void sendFile(const TQString &uid, const KURL &sourceURL,
		const TQString &altFileName = TQString::null, uint fileSize = 0) = 0;

// MUTATORS
// Contact list
	/**
	 * @brief Add a new contact given its protocol specific identifier
	 *
	 * Implementations might add the contact silently, including sending an
	 * authorization request if necessary, ask the user for confirmation or
	 * just prefill the usual contact addingGUI.
	 *
	 * @param contactId the protocol specific identifier for the contact
	 *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
	 * @param protocol the IM protocol/service to use. See protocols()
	 * @return whether the add succeeded. @c false may signal already present,
	 *         protocol not supported, or add operation not supported.
	 *
	 * @see locate()
	 * @see protocols()
	 * @see messageNewContact()
	 */
	virtual bool addContact( const TQString &contactId, const TQString &protocol ) = 0;

// SIGNALS
k_dcop_signals:
	/**
	 * @brief Indicates that a contact's presence has changed
	 *
	 * Notifies connected DCOP receivers about a change in a contact's
	 * presence.
	 *
	 * Implementations just have to call this method with the appropriate
	 * values to get the DCOP signal emitted.
	 *
	 * @param uid the KABC UID whose presence changed
	 * @param appId the DCOP application ID of the program the signal
	 *        originates from
	 * @param presence the new presence's numeric value. See presenceStatus()
	 *
	 * @see presenceStatus()
	 * @see KABC::Addressee::uid()
	 * @see DCOPClient::appId()
	 */
	void contactPresenceChanged( TQString uid, TQCString appId, int presence );
};

#endif



/*
 * Local variables:
 * c-indentation-style: k&r
 * c-basic-offset: 8
 * indent-tabs-mode: t
 * End:
 */
// vim: set noet ts=4 sts=4 sw=4: