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