1 /****************************************************************************
2 ** Copyright (C) 2010-2020 Klaralvdalens Datakonsult AB, a KDAB Group company, info@kdab.com.
3 ** All rights reserved.
4 **
5 ** This file is part of the KD Soap library.
6 **
7 ** Licensees holding valid commercial KD Soap licenses may use this file in
8 ** accordance with the KD Soap Commercial License Agreement provided with
9 ** the Software.
10 **
11 **
12 ** This file may be distributed and/or modified under the terms of the
13 ** GNU Lesser General Public License version 2.1 and version 3 as published by the
14 ** Free Software Foundation and appearing in the file LICENSE.LGPL.txt included.
15 **
16 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
17 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
18 **
19 ** Contact info@kdab.com if any conditions of this licensing are not
20 ** clear to you.
21 **
22 **********************************************************************/
23 #ifndef KDSOAPJOB_H
24 #define KDSOAPJOB_H
25 
26 #include "KDSoapGlobal.h"
27 
28 #include <QtCore/QObject>
29 
30 class KDSoapMessage;
31 class KDSoapHeaders;
32 
33 /**
34  * \brief KDSoapJob provides a job-based interface to handle asynchronous KD Soap calls.
35  *
36  * For each SOAP operation, kdwsdl2cpp generates a corresponding KDSoapJob subclass.
37  * This makes it easier to manage multiple callers in the client application code calling the same functions, preventing
38  * callers processing results for calls made from another caller instead of their own calls.
39  *
40  * For example, a call to getMothersDay (from the holidays example) using the conventional asynchronous API would look like this:
41  * \code
42  *  connect(client, SIGNAL(getMothersDayDone(TNS__GetMothersDayResponse)), this, SLOT(getMothersDayDone(TNS__GetMothersDayResponse)));
43  *  connect(client, SIGNAL(getMothersDayError(KDSoapMessage)), this, SLOT(getMothersDayError(KDSoapMessage)));
44  *  TNS__GetMothersDay params;
45  *  params.setYear(2012);
46  *  client->asyncGetMothersDay(params);
47  * \endcode
48  *
49  * In this example, all responses to getMothersDay made \c client will be received by the slots connected above.
50  * Using the job-based API, it becomes:
51  *
52  * \code
53  *  GetMothersDayJob* job = new GetMothersDayJob(client);
54  *  connect(job, SIGNAL(finished(KDSoapJob*)), this, SLOT(getMothersDayDone(KDSoapJob*)));
55  *  TNS__GetMothersDay params;
56  *  params.setYear(2012);
57  *  job->setParameters(params);
58  *  job->start();
59  * \endcode
60  *
61  * Now only the result of this specific getMothersDay call will be received by the slot.
62  *
63  * \since 1.2
64  */
65 class KDSOAP_EXPORT KDSoapJob : public QObject
66 {
67     Q_OBJECT
68 public:
69     /**
70      * Constructs a KD Soap job.
71      *
72      * \param parent optional parent object
73      */
74     explicit KDSoapJob(QObject *parent = nullptr);
75 
76     /**
77      * Destructor.
78      */
79     ~KDSoapJob();
80 
81     /**
82      * Returns the reply headers received from the SOAP server once the request was completed.
83      * Only valid once the request is completed and finished() was emitted.
84      */
85     KDSoapHeaders requestHeaders() const;
86 
87     /**
88      * Sets request headers to be sent to the SOAP server. These are sent in addition
89      * to the persistent headers set via the client interface.
90      *
91      * \since 1.8
92      */
93     void setRequestHeaders(const KDSoapHeaders &headers);
94 
95     /**
96      * Returns whether the reply message (see reply()) represents a fault.
97      */
98     bool isFault() const;
99 
100     /**
101      * A human-readable error string describing the fault if the reply message is a fault, an empty string otherwise.
102      */
103     QString faultAsString() const;
104 
105     /**
106      * Returns the reply message received from the SOAP server once the request was completed.
107      * Only valid once the request is completed and finished() was emitted.
108      */
109     KDSoapMessage reply() const;
110 
111     /**
112      * Returns the reply headers received from the SOAP server once the request was completed.
113      * Only valid once the request is completed and finished() was emitted.
114      *
115      * \since 1.8
116      */
117     KDSoapHeaders replyHeaders() const;
118 
119     /**
120      * Starts the job. The job will emit finished() once done.
121      */
122     void start();
123 
124     /**
125      * Defines whether the job should be automatically deleted or not.
126      * \since 1.8
127      */
128     void setAutoDelete(bool enable);
129 
130 Q_SIGNALS:
131     /**
132      * emitted when the job is completed, i.e. the reply for the job's request
133      * was received. To read the result, call reply() in the connected slot.
134      * Do not delete the job, the job will auto-delete itself. This behavior
135      * can be changed with setAutoDelete().
136      *
137      * \param job The job instance that emitted the signal
138      */
139     void finished(KDSoapJob *job);
140 
141 protected:
142     /**
143      * \internal
144      * Reimplemented in kdwsdl2cpp-generated classes to start request asynchronously.
145      */
146     Q_INVOKABLE virtual void doStart() = 0;
147 
148     /**
149      * \internal
150      * Sets reply, emits finished() signal and manages deletion of job
151      */
152     void emitFinished(const KDSoapMessage &reply, const KDSoapHeaders &replyHeaders);
153 
154 private:
155     class Private;
156     Private *const d;
157 };
158 
159 #endif // KDSOAPJOB_H
160