1/******************************************************************************
2 * Copyright (C) 2003 - 2004 by Frerich Raabe <raabe@kde.org> *
3 * Tobias Koenig <tokoe@kde.org> *
4 * Copyright (C) 2006 by Narayan Newton <narayannewton@gmail.com> *
5 * *
6 * This program is distributed in the hope that it will be useful, but *
7 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY *
8 * or FITNESS FOR A PARTICULAR PURPOSE. For licensing and distribution *
9 * details, check the accompanying file 'COPYING.BSD'. *
10 *****************************************************************************/
11/**
12 @file
13 This file is part of the API for accessing XML-RPC Servers
14 and defines the Client class.
15
16 @brief
17 Defines the Client class.
18
19 @author Frerich Raabe <raabe@kde.org>
20 @author Tobias Koenig <tokoe@kde.org>
21 @author Narayan Newton <narayannewton@gmail.com>
22*/
23
24#ifndef KXML_RPC_CLIENT_H
25#define KXML_RPC_CLIENT_H
26
27#include "kxmlrpcclient_export.h"
28
29#include <kurl.h>
30
31#include <QtCore/QList>
32#include <QtCore/QObject>
33#include <QtCore/QVariant>
34
35/** Names for XmlRpc related classes */
36namespace KXmlRpc {
37
38/**
39 @brief
40 A class that represents a connection to a XML-RPC server.
41 This is the main interface to the XML-RPC client library.
42
43 @code
44 KXmlRpc::Client *c = new Client(KUrl( "http://localhost" ), this);
45 c->setUserAgent( "Test/1.0" );
46 c->call( "xmlrpc.command1", "Hi!",
47 this, SLOT( gotData( const QList<QVariant>&, const QVariant ) ),
48 this, SLOT( gotError( const QString&, const QVariant& ) ) );
49 @endcode
50
51 @author Narayan Newton <narayannewton@gmail.com>
52 */
53class KXMLRPCCLIENT_EXPORT Client : public QObject
54{
55 Q_OBJECT
56
57 public:
58 /**
59 Constructs a XML-RPC Client.
60
61 @param parent the parent of this object, defaults to NULL.
62 */
63 explicit Client( QObject *parent = 0 );
64
65 /**
66 Constructs a XML-RPC Client, which will connect to @p url.
67
68 @param url the url of the xml-rpc server.
69 @param parent the parent of this object, defaults to NULL.
70 */
71 explicit Client( const KUrl &url, QObject *parent = 0 );
72
73 /**
74 Destroys the XML-RPC Client.
75 */
76 ~Client();
77
78 /**
79 Returns the current url the XML-RPC Client will connect to.
80
81 @see setUrl()
82 */
83 KUrl url() const;
84
85 /**
86 Sets the url the Client will connect to.
87
88 @param url the url for the xml-rpc server we will be connecting to.
89
90 @see url()
91 */
92 void setUrl( const KUrl &url );
93
94 /**
95 Returns the user agent string currently used by the Client.
96
97 @see setUserAgent()
98 */
99 QString userAgent() const;
100
101 /**
102 Sets the userAgent string the Client will use to identify itself.
103
104 @param userAgent the user agent string to use.
105
106 @see userAgent()
107 */
108 void setUserAgent( const QString &userAgent );
109
110 /**
111 Returns true if HTTP-Digest authentication is enabled, false
112 if not.
113
114 @see setDigestAuthEnabled()
115 */
116 bool isDigestAuthEnabled() const;
117
118 /**
119 Enables/disables HTTP-Digest authentication
120
121 @see isDigestAuthEnabled()
122 */
123
124 void setDigestAuthEnabled( bool enabled );
125
126 public Q_SLOTS:
127 /**
128 Calls the given method on a XML-RPC server, with the given
129 argument list.
130
131 @param method the method on the server we are going to be calling
132 @param args the argument list to pass to the server
133 @param msgObj the object containing the data slot
134 @param messageSlot the data slot itself
135 @param faultObj the object containing the error slot
136 @param faultSlot the error slot itself
137 @param id the id for our #Client object, defaults to empty
138 */
139 void call( const QString &method, const QList<QVariant> &args,
140 QObject *msgObj, const char *messageSlot,
141 QObject *faultObj, const char *faultSlot,
142 const QVariant &id = QVariant() );
143
144 /**
145 Calls the given method on a XML-RPC server, with the given
146 argument.
147
148 @param method the method on the server we are going to be calling
149 @param arg the argument to pass to the server
150 @param msgObj the object containing the data slot
151 @param messageSlot the data slot itself
152 @param faultObj the object containing the error slot
153 @param faultSlot the error slot itself
154 @param id the id for our Client object, defaults to empty
155 */
156 void call( const QString &method, const QVariant &arg,
157 QObject *msgObj, const char *messageSlot,
158 QObject *faultObj, const char *faultSlot,
159 const QVariant &id = QVariant() );
160
161 /**
162 Calls the given method on a XML-RPC server, with the given
163 int as the argument.
164
165 @param method the method on the server we are going to be calling
166 @param arg the int to pass to the server
167 @param msgObj the object containing the data slot
168 @param messageSlot the data slot itself
169 @param faultObj the object containing the error slot
170 @param faultSlot the error slot itself
171 @param id the id for our Client object, defaults to empty
172 */
173 void call( const QString &method, int arg,
174 QObject *msgObj, const char *messageSlot,
175 QObject *faultObj, const char *faultSlot,
176 const QVariant &id = QVariant() );
177
178 /**
179 Calls the given method on a XML-RPC server, with the given
180 bool as the argument.
181
182 @param method the method on the server we are going to be calling
183 @param arg the bool to pass to the server
184 @param msgObj the object containing the data slot
185 @param messageSlot the data slot itself
186 @param faultObj the object containing the error slot
187 @param faultSlot the error slot itself
188 @param id the id for our Client object, defaults to empty
189 */
190 void call( const QString &method, bool arg,
191 QObject *msgObj, const char *messageSlot,
192 QObject *faultObj, const char *faultSlot,
193 const QVariant &id = QVariant() );
194
195 /**
196 Calls the given method on a XML-RPC server, with the given
197 double as the argument.
198
199 @param method the method on the server we are going to be calling
200 @param arg the double to pass to the server
201 @param msgObj the object containing the data slot
202 @param messageSlot the data slot itself
203 @param faultObj the object containing the error slot
204 @param faultSlot the error slot itself
205 @param id the id for our Client object, defaults to empty
206 */
207 void call( const QString &method, double arg,
208 QObject *msgObj, const char *messageSlot,
209 QObject *faultObj, const char *faultSlot,
210 const QVariant &id = QVariant() );
211
212 /**
213 Calls the given method on a XML-RPC server, with the given
214 string as the argument.
215
216 @param method the method on the server we are going to be calling
217 @param arg the string to pass to the server
218 @param msgObj the object containing the data slot
219 @param messageSlot the data slot itself
220 @param faultObj the object containing the error slot
221 @param faultSlot the error slot itself
222 @param id the id for our Client object, defaults to empty
223 */
224 void call( const QString &method, const QString &arg,
225 QObject *msgObj, const char *messageSlot,
226 QObject *faultObj, const char *faultSlot,
227 const QVariant &id = QVariant() );
228
229 /**
230 Calls the given method on a XML-RPC server, with the given
231 byte array as the argument.
232
233 @param method the method on the server we are going to be calling
234 @param arg the array to pass to the server
235 @param msgObj the object containing the data slot
236 @param messageSlot the data slot itself
237 @param faultObj the object containing the error slot
238 @param faultSlot the error slot itself
239 @param id the id for our Client object, defaults to empty
240 */
241 void call( const QString &method, const QByteArray &arg,
242 QObject *msgObj, const char *messageSlot,
243 QObject *faultObj, const char *faultSlot,
244 const QVariant &id = QVariant() );
245
246 /**
247 Calls the given method on a XML-RPC server, with the given
248 date as the argument
249
250 @param method the method on the server we are going to be calling
251 @param arg the date and/or time to pass to the server
252 @param msgObj the object containing the data slot
253 @param messageSlot the data slot itself
254 @param faultObj the object containing the error slot
255 @param faultSlot the error slot itself
256 @param id the id for our Client object, defaults to empty
257 */
258 void call( const QString &method, const QDateTime &arg,
259 QObject *msgObj, const char *messageSlot,
260 QObject *faultObj, const char *faultSlot,
261 const QVariant &id = QVariant() );
262
263 /**
264 Calls the given method on a XML-RPC server, with the given
265 string list as the argument
266
267 @param method the method on the server we are going to be calling
268 @param arg the list of strings to pass to the server
269 @param msgObj the object containing the data slot
270 @param messageSlot the data slot itself
271 @param faultObj the object containing the error slot
272 @param faultSlot the error slot itself
273 @param id the id for our Client object, defaults to empty
274 */
275 void call( const QString &method, const QStringList &arg,
276 QObject *msgObj, const char *messageSlot,
277 QObject *faultObj, const char *faultSlot,
278 const QVariant &id = QVariant() );
279
280 private:
281 class Private;
282 Private *const d;
283
284 template <typename T>
285 void call( const QString &method, const QList<T> &arg,
286 QObject *obj1, const char *messageSlot,
287 QObject *obj2, const char *faultSlot,
288 const QVariant &id = QVariant() );
289
290 Q_PRIVATE_SLOT( d, void queryFinished( Query * ) )
291};
292
293/**
294 Calls the given method on a XML-RPC server with the given
295 list of type T arguments.
296
297 @param method the method on the server we are going to be calling
298 @param arg the list of type T to pass to the server
299 @param msgObj the object containing the data slot
300 @param messageSlot the data slot itself
301 @param faultObj the object containing the error slot
302 @param faultSlot the error slot itself
303 @param id the id for our Client object, defaults to empty
304*/
305template <typename T>
306void Client::call( const QString &method, const QList<T> &arg,
307 QObject *msgObj, const char *messageSlot,
308 QObject *faultObj, const char *faultSlot,
309 const QVariant &id )
310{
311 QList<QVariant> args;
312
313 for ( int i = 0; i < arg.count(); ++i ) {
314 args << QVariant( arg[ i ] );
315 }
316
317 return call( method, args, faultObj, faultSlot, msgObj, messageSlot, id );
318}
319
320}
321
322#endif
323