1/*
2 kimproxy.h
3
4 IM service library for KDE
5
6 Copyright (c) 2004 Will Stephenson <lists@stevello.free-online.co.uk>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22*/
23
24#ifndef KIMPROXY_H
25#define KIMPROXY_H
26
27#include <QtCore/QHash>
28#include <QtCore/QMap>
29#include <QtCore/QStringList>
30#include <QtGui/QPixmap>
31
32#include <kimproxy_export.h>
33
34#define IM_SERVICE_TYPE "DBUS/InstantMessenger"
35#define IM_CLIENT_PREFERENCES_FILE "default_components"
36#define IM_CLIENT_PREFERENCES_SECTION "InstantMessenger"
37#define IM_CLIENT_PREFERENCES_ENTRY "imClient"
38
39class KUrl;
40class ContactPresenceListCurrent;
41class OrgKdeKIMInterface;
42
43/** FIXME: remove for KDE4, binary compatibility again. */
44typedef QMap<QString, int> AppPresence; // appId->presence; contains all applications' ideas of a user's presence
45typedef QHash<QString, AppPresence*> PresenceMap; // uid->AppPresence; contains a AppPresences for all users
46/** FIXME: remove presenceMap and call this presenceMap in KDE4. This hack is for binary compatibility */
47typedef QMap<QString, ContactPresenceListCurrent> PresenceStringMap;
48
49/**
50 * This class provides an easy-to-use interface to any instant messengers or chat programs
51 * that you have installed that implement KIMIface
52 *
53 * It works simultaneously with any running programs that implement the ServiceType DBUS/InstantMessenger
54 * If a UID is reachable with more than one program, KIMProxy aggregates the available information and presents
55 * the 'best' presence. For example, for a contact who can be seen to be Away in IRC on program A but Online using
56 * ICQ on program B, the information from program B will be used. KIMProxy is designed for simple information in
57 * a wide number of cases, not for detailed messaging.
58 *
59 * Most operations work in terms of uids belonging to KABC::Addressee, but use of the
60 * address book is optional. You can get a list of known contacts with imAddresseeUids
61 * and then check their presence using the various accessor methods presenceString, presenceNumeric
62 * and display the IM programs' display names for them using displayName.
63 *
64 * To use, just get an instance using @ref instance.
65 *
66 * @author Will Stephenson <lists@stevello.free-online.co.uk>
67 */
68class KIMPROXY_EXPORT KIMProxy : public QObject
69{
70 Q_OBJECT
71 public:
72 ~KIMProxy();
73 /**
74 * Obtain an instance of KIMProxy.
75 * @return The singleton instance of this class.
76 */
77 static KIMProxy * instance();
78
79 /**
80 * Get the proxy ready to connect
81 * Discover any running preferred IM clients and set up stubs for it
82 * @return whether the proxy is ready to use. False if there are no apps running.
83 */
84 bool initialize();
85
86 public Q_SLOTS:
87 /**
88 * Obtain a list of IM-contactable entries in the KDE
89 * address book.
90 * @return a list of KABC uids.
91 */
92 QStringList allContacts();
93
94 /**
95 * Obtain a list of KDE address book entries who are
96 * currently reachable.
97 * @return a list of KABC uids who can receive a message, even if online.
98 */
99 QStringList reachableContacts();
100
101 /**
102 * Obtain a list of KDE address book entries who are
103 * currently online.
104 * @return a list of KABC uids who are online with unspecified presence.
105 */
106 QStringList onlineContacts();
107
108 /**
109 * Obtain a list of KDE address book entries who may
110 * receive file transfers.
111 * @return a list of KABC uids capable of file transfer.
112 */
113 QStringList fileTransferContacts();
114
115 /**
116 * Confirm if a given KABC uid is known to KIMProxy
117 * @param uid the KABC uid you are interested in.
118 * @return whether one of the chat programs KIMProxy talks to knows of this KABC uid.
119 */
120 bool isPresent( const QString& uid );
121
122 /**
123 * Obtain the IM app's idea of the contact's display name
124 * Useful if KABC lookups may be too slow
125 * @param uid the KABC uid you are interested in.
126 * @return The corresponding display name.
127 */
128 QString displayName( const QString& uid );
129
130 /**
131 * Obtain the IM presence as a number (see KIMIface) for the specified addressee
132 * @param uid the KABC uid you want the presence for.
133 * @return a numeric representation of presence - currently one of 0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online)
134 */
135 int presenceNumeric( const QString& uid );
136
137 /**
138 * Obtain the IM presence as a i18ned string for the specified addressee
139 * @param uid the KABC uid you want the presence for.
140 * @return the i18ned string describing presence.
141 */
142 QString presenceString( const QString& uid );
143
144 /**
145 * Obtain the icon representing IM presence for the specified addressee
146 * @param uid the KABC uid you want the presence for.
147 * @return a pixmap representing the uid's presence.
148 */
149 QPixmap presenceIcon( const QString& uid );
150
151 /**
152 * Indicate if a given uid can receive files
153 * @param uid the KABC uid you are interested in.
154 * @return Whether the specified addressee can receive files.
155 */
156 bool canReceiveFiles( const QString & uid );
157
158 /**
159 * Some media are unidirectional (eg, sending SMS via a web interface).
160 * @param uid the KABC uid you are interested in.
161 * @return Whether the specified addressee can respond.
162 */
163 bool canRespond( const QString & uid );
164
165 /**
166 * Get the KABC uid corresponding to the supplied IM address
167 * Protocols should be
168 * @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
169 * @param protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol",
170 * @return a KABC uid or null if none found/
171 */
172 QString locate( const QString & contactId, const QString & protocol );
173
174 /**
175 * Get the supplied addressee's current context (home, work, or any).
176 * @param uid the KABC uid you want the context for.
177 * @return A QString describing the context, or null if not supported.
178 */
179 QString context( const QString & uid );
180
181 /**
182 * Start a chat session with the specified addressee
183 * @param uid the KABC uid you want to chat with.
184 */
185 void chatWithContact( const QString& uid );
186
187 /**
188 * Send a single message to the specified addressee
189 * Any response will be handled by the IM client as a normal
190 * conversation.
191 * @param uid the KABC uid you want to chat with.
192 * @param message the message to send them.
193 */
194 void messageContact( const QString& uid, const QString& message );
195
196 /**
197 * Send the file to the contact
198 * @param uid the KABC uid you are sending to.
199 * @param sourceURL a KUrl to send.
200 * @param altFileName an alternate filename describing the file
201 * @param fileSize file size in bytes
202 */
203 void sendFile(const QString &uid, const QString &sourceURL, const QString &altFileName = QString(), uint fileSize = 0);
204
205 /**
206 * Add a contact to the contact list
207 * @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
208 * @param protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol",
209 * @return whether the add succeeded. False may signal already present, protocol not supported, or add operation not supported.
210 */
211 bool addContact( const QString &contactId, const QString &protocol );
212
213 /**
214 * Are there any compatible instant messaging apps installed?
215 * @return true if there are any apps installed, to see if they are running, @ref initialize instead.
216 */
217 bool imAppsAvailable();
218
219 /**
220 * Start the user's preferred IM application
221 * @return whether a preferred app was found. No guarantee that it started correctly
222 */
223 bool startPreferredApp();
224
225 /**
226 * Just exists to let the idl compiler make the D-Bus signal for this
227 */
228 void contactPresenceChanged( const QString& uid, const QString& appId, int presence );
229
230 private Q_SLOTS:
231 void nameOwnerChanged( const QString &name, const QString &oldOwner, const QString &newOwner);
232 Q_SIGNALS:
233 /**
234 * Indicates that the specified UID's presence changed
235 * @param uid the KABC uid whose presence changed.
236 */
237 void sigContactPresenceChanged( const QString &uid );
238
239 /**
240 * Indicates that the sources of presence information have changed
241 * so any previously supplied presence info is invalid.
242 */
243 void sigPresenceInfoExpired();
244 protected:
245 /**
246 * Bootstrap our presence data for a newly registered app
247 */
248 void pollApp( const QString & appId );
249 /**
250 * Bootstrap our presence data by polling all known apps
251 */
252 void pollAll( const QString &uid );
253
254 /**
255 * Update our records with the given data
256 */
257 bool updatePresence( const QString &uid, const QString &appId, int presence );
258
259 /**
260 * Get the name of the user's IM weapon of choice
261 */
262 QString preferredApp();
263
264 /**
265 * Get the app stub best able to reach this uid
266 */
267 OrgKdeKIMInterface * stubForUid( const QString &uid );
268
269 /**
270 * Get the app stub for this protocol.
271 * Take the preferred app first, then any other.
272 */
273 OrgKdeKIMInterface * stubForProtocol( const QString &protocol );
274
275 private:
276 // client stubs used to get presence
277 // appId (from D-Bus) -> KIMIface_stub
278 QHash<QString, OrgKdeKIMInterface*> m_im_client_stubs;
279 // map containing numeric presence and the originating application ID for each KABC uid we know of
280 // KABC Uid -> (appId, numeric presence )(AppPresence)
281 PresenceMap m_presence_map;
282 // cache of the client strings in use by each application
283 // dictionary of KIMIface_stub -> map of numeric presence -> string presence
284 class Private;
285
286 Private * const d;
287 bool m_apps_available;
288 bool m_initialized;
289 /**
290 * Construct an instance of the proxy library.
291 */
292 KIMProxy();
293};
294
295#endif
296
297