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
|
/*
kimiface.h - KDE Instant Messenger DCOP Interface
Copyright (c) 2004 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>
/**
* Generic DCOP interface for TDE instant messenger applications
* Note one omission of this interface is the lack of control over the range of values used for protocols' names.
* @since 3.3
* @author Will Stephenson <lists@stevello.free-online.co.uk>
*/
class KIMIface : virtual public DCOPObject
{
K_DCOP
k_dcop:
// ACCESSORS
// contact list
/**
* Obtain a list of IM-contactable entries in the TDE
* address book.
* @return a list of KABC uids.
*/
virtual TQStringList allContacts() = 0;
/**
* Obtain a list of TDE address book entries who are
* currently reachable.
* @return a list of KABC uids who can receive a message, even if online.
*/
virtual TQStringList reachableContacts() = 0;
/**
* Obtain a list of TDE address book entries who are
* currently online.
* @return a list of KABC uids who are online with unspecified presence.
*/
virtual TQStringList onlineContacts() = 0;
/**
* Obtain a list of TDE address book entries who may
* receive file transfers.
* @return a list of KABC uids capable of file transfer.
*/
virtual TQStringList fileTransferContacts() = 0;
// individual
/**
* Confirm if a given KABC uid is known to KIMProxy
* @param uid the KABC uid you are interested in.
* @return whether one of the chat programs KIMProxy talks to knows of this KABC uid.
*/
virtual bool isPresent( const TQString & uid ) = 0;
/**
* Obtain the IM app's idea of the contact's display name
* Useful if KABC lookups may be too slow
* @param KABC uid.
* @return The corresponding display name.
*/
virtual TQString displayName( const TQString & uid ) = 0;
/**
* Obtain the IM presence as a i18ned string for the specified addressee
* @param uid the KABC uid you want the presence for.
* @return the i18ned string describing presence.
*/
virtual TQString presenceString( const TQString & uid ) = 0;
/**
* Obtain the IM presence as a number (see KIMIface) for the specified addressee
* @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)
*/
virtual int presenceStatus( const TQString & uid ) = 0;
/**
* Indicate if a given uid can receive files
* @param uid the KABC uid you are interested in.
* @return Whether the specified addressee can receive files.
*/
virtual bool canReceiveFiles( const TQString & uid ) = 0;
/**
* Some media are unidirectional (eg, sending SMS via a web interface).
* @param uid the KABC uid you are interested in.
* @return Whether the specified addressee can respond.
*/
virtual bool canRespond( const TQString & uid ) = 0;
/**
* Get the KABC uid corresponding to the supplied IM address
* Protocols should be
* @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
* @param protocol the protocol, eg one of "AIMProtocol", "ICQProtocol",
* @return a KABC uid or null if none found/
*/
virtual TQString locate( const TQString & contactId, const TQString & protocol ) = 0;
// metadata
/**
* Obtain the icon representing IM presence for the specified addressee
* @param uid the KABC uid you want the presence for.
* @return a pixmap representing the uid's presence.
*/
virtual TQPixmap icon( const TQString & uid ) = 0;
/**
* Get the supplied addressee's current context (home, work, or any).
* @param uid the KABC uid you want the context for.
* @return A TQString describing the context, or null if not supported.
*/
virtual TQString context( const TQString & uid ) = 0;
// App capabilities
/**
* Discover what protocols the application supports
* @return the set of protocols that the application supports
*/
virtual TQStringList protocols() = 0;
// ACTORS
/**
* Send a single message to the specified addressee
* Any response will be handled by the IM client as a normal
* conversation.
* @param uid the KABC uid you want to chat with.
* @param message the message to send them.
*/
virtual void messageContact( const TQString &uid, const TQString& message ) = 0;
/**
* Open a chat to a contact, and optionally set some initial text
*/
virtual void messageNewContact( const TQString &contactId, const TQString &protocol ) = 0;
/**
* Start a chat session with the specified addressee
* @param uid the KABC uid you want to chat with.
*/
virtual void chatWithContact( const TQString &uid ) = 0;
/**
* Send the file to the contact
* @param uid the KABC uid you are sending to.
* @param sourceURL a @ref KURL to send.
* @param altFileName an alternate filename describing the file
* @param fileSize file size in bytes
*/
virtual void sendFile(const TQString &uid, const KURL &sourceURL,
const TQString &altFileName = TQString(), uint fileSize = 0) = 0;
// MUTATORS
// Contact list
/**
* Add a contact to the contact list
* @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
* @param protocol the protocol, eg one of "AIMProtocol", "ICQProtocol", ...
* @return whether the add succeeded. False may signal already present, protocol not supported, or add operation not supported.
*/
virtual bool addContact( const TQString &contactId, const TQString &protocol ) = 0;
// SIGNALS
k_dcop_signals:
/**
* Indicates that a contact's presence has changed
* @param uid the contact whose presence changed.
* @param appId the dcop application id of the program the signal originates from.
* @param presence the new numeric presence @ref presenceStatus
*/
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:
|
