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