1 /* This file is part of the KDE project
2    Copyright (C) 2003 Joseph Wenninger <jowenn@kde.org>
3    Copyright (C) 2003-2015 Jarosław Staniek <staniek@kde.org>
4 
5    This program is free software; you can redistribute it and/or
6    modify it under the terms of the GNU Library General Public
7    License as published by the Free Software Foundation; either
8    version 2 of the License, or (at your option) any later version.
9 
10    This program is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    Library General Public License for more details.
14 
15    You should have received a copy of the GNU Library General Public License
16    along with this program; see the file COPYING.  If not, write to
17    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18  * Boston, MA 02110-1301, USA.
19 */
20 
21 #ifndef KDB_RESULT_H
22 #define KDB_RESULT_H
23 
24 #include "KDbEscapedString.h"
25 #include "KDbError.h"
26 
27 #include <QCoreApplication>
28 
29 class KDbMessageHandler;
30 class KDbMessageTitleSetter;
31 
32 /*! Stores detailed information about result of recent operation.
33 */
34 class KDB_EXPORT KDbResult //SDC: virtual_dtor operator==
35 {
36     Q_DECLARE_TR_FUNCTIONS(KDbResult)
37 public:
38     /*!
39     @getter
40     @return result code, default is ERR_NONE (0).
41     @setter
42     Sets the result code if there was error.
43     */
44     int code; //SDC: default=ERR_NONE default_setter=ERR_OTHER
45 
46     /*!
47     @getter
48     @return an implementation-specific last server-side operation result number.
49     Use this to give users more precise information about the result.
50 
51     For example, use this for your driver - default implementation just returns 0.
52     Note that this value is not the same as the one returned by code().
53     @sa serverMessage()
54     */
55     int serverErrorCode; //SDC: default=0 no_setter
56 
57     /*!
58     @getter
59     @return (localized) message if there was error.
60     @setter
61     Sets (localized) message to @a message.
62     */
63     QString message; //SDC:
64 
65     /*!
66     @getter
67     @return message title that sometimes is provided and prepended
68     to the main warning/error message. Used by KDbMessageHandler.
69     */
70     QString messageTitle; //SDC:
71 
72     KDbEscapedString errorSql; //SDC:
73 
74     KDbEscapedString sql; //SDC:
75 
76     /*!
77     @getter
78     @return message from server.
79     KDb framework offers detailed result numbers using resultCode() and detailed
80     result i18n-ed messages using message(). These both are (almost) not engine-dependent.
81     Use setServerMessage() to users more information on the result of operation that is
82     non-i18n-ed and engine-specific, usually coming from the server server side.
83     @setter
84     Sets message from the server.
85     */
86     QString serverMessage; //SDC:
87 
88     bool serverErrorCodeSet; //SDC: default=false no_getter no_setter
89 
90     KDbResult(int code, const QString& message);
91 
92     explicit KDbResult(const QString& message);
93 
94     //! @return true if there is an error i.e. a nonempty message, error code other
95     //!         than ERR_NONE or server result has been set.
96     bool isError() const;
97 
98     //! Sets an implementation-specific error code of server-side operation.
99     //! Use this to give users more precise information. Implies isError() == true.
100     //! The only way to clear already set server result code is to create a new KDbResult object.
101     void setServerErrorCode(int errorCode);
102 
103     //! Sets result code and prepends message to an existing message.
104     void prependMessage(int code, const QString& message);
105 
106     //! Prepends message to an existing message.
107     void prependMessage(const QString& message);
108 
109     //! Efficient clearing of the sql attribute, equivalent of setSql(QString()).
clearSql()110     inline void clearSql() {
111         d->sql.clear();
112     }
113 
114     /*! @return sql string of actually executed SQL statement,
115      usually using drv_executeSql(). If there was error during executing SQL statement,
116      before, that string is returned instead. */
recentSqlString()117     virtual inline KDbEscapedString recentSqlString() const {
118         return d->errorSql;
119     }
120 
121 protected:
122     void init(int code, const QString& message);
123 #if 0
124     /*! Interactively asks a question. Console or GUI can be used for this,
125      depending on installed message handler. For GUI version, message boxes are used.
126      See KDbMessageHandler::askQuestion() for details. */
127     virtual KDbMessageHandler::ButtonCode askQuestion(
128             KDbMessageHandler::QuestionType messageType,
129             const QString& message,
130             const QString &caption = QString(),
131             KDbMessageHandler::ButtonCode defaultResult = KDbMessageHandler::Yes,
132             const KDbGuiItem &buttonYes = KDbGuiItem(),
133             const KDbGuiItem &buttonNo = KDbGuiItem(),
134             const QString &dontShowAskAgainName = QString(),
135             KDbMessageHandler::Options options = 0,
136             KDbMessageHandler* msgHandler = 0);
137 
138     /*! Clears number of last server operation's result stored
139      as a single integer. Formally, this integer should be set to value
140      that means "NO ERRORS" or "OK". This method is called by clearError().
141      For reimplementation. By default does nothing.
142      @sa serverMessage()
143     */
144     virtual void drv_clearServerResultCode() {}
145 #endif
146 };
147 
148 //! Interface for classes providing a result.
149 class KDB_EXPORT KDbResultable
150 {
151 public:
152     KDbResultable();
153 
154     KDbResultable(const KDbResultable &other);
155 
156     KDbResultable& operator=(const KDbResultable &other);
157 
158     virtual ~KDbResultable();
159 
160     KDbResult result() const;
161 
162     void clearResult();
163 
164     /*! @return engine-specific last server-side operation result name, a name for KDbResult::serverErrorCode().
165     Use this in your application to give users more information on what's up.
166 
167     Use this for your driver - default implementation just returns empty string.
168     Note that this result name is not the same as the error message returned by KDbResult::serverMessage() or KDbResult::message().
169     @sa KDbResult::serverMessage() */
170     virtual QString serverResultName() const;
171 
172     //! Sets message handler to @a handler.
173     void setMessageHandler(KDbMessageHandler *handler);
174 
175     //! @return associated message handler. 0 by default.
176     KDbMessageHandler* messageHandler() const;
177 
178     void showMessage();
179 
180 protected:
181     friend class KDbMessageTitleSetter;
182     KDbResult m_result;
183     class Private;
184     Private * const d;
185 };
186 
187 //! Sends result @a result to debug output @a dbg.
188 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbResult& result);
189 
190 #endif // KDB_RESULT_H
191