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 | |
39 | class KUrl; |
40 | class ContactPresenceListCurrent; |
41 | class OrgKdeKIMInterface; |
42 | |
43 | /** FIXME: remove for KDE4, binary compatibility again. */ |
44 | typedef QMap<QString, int> AppPresence; // appId->presence; contains all applications' ideas of a user's presence |
45 | typedef 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 */ |
47 | typedef 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 | */ |
68 | class 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 | |