File indexing completed on 2024-12-01 07:24:59
0001 /* This file is part of the KDE project 0002 Copyright (C) 2003 Joseph Wenninger <jowenn@kde.org> 0003 Copyright (C) 2003-2015 Jarosław Staniek <staniek@kde.org> 0004 0005 This program is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Library General Public 0007 License as published by the Free Software Foundation; either 0008 version 2 of the License, or (at your option) any later version. 0009 0010 This program is distributed in the hope that it will be useful, 0011 but WITHOUT ANY WARRANTY; without even the implied warranty of 0012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0013 Library General Public License for more details. 0014 0015 You should have received a copy of the GNU Library General Public License 0016 along with this program; see the file COPYING. If not, write to 0017 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0018 * Boston, MA 02110-1301, USA. 0019 */ 0020 0021 #ifndef KDB_RESULT_H 0022 #define KDB_RESULT_H 0023 0024 #include "KDbEscapedString.h" 0025 #include "KDbError.h" 0026 0027 #include <QCoreApplication> 0028 0029 class KDbMessageHandler; 0030 class KDbMessageTitleSetter; 0031 0032 /*! Stores detailed information about result of recent operation. 0033 */ 0034 class KDB_EXPORT KDbResult //SDC: virtual_dtor operator== 0035 { 0036 Q_DECLARE_TR_FUNCTIONS(KDbResult) 0037 public: 0038 /*! 0039 @getter 0040 @return result code, default is ERR_NONE (0). 0041 @setter 0042 Sets the result code if there was error. 0043 */ 0044 int code; //SDC: default=ERR_NONE default_setter=ERR_OTHER 0045 0046 /*! 0047 @getter 0048 @return an implementation-specific last server-side operation result number. 0049 Use this to give users more precise information about the result. 0050 0051 For example, use this for your driver - default implementation just returns 0. 0052 Note that this value is not the same as the one returned by code(). 0053 @sa serverMessage() 0054 */ 0055 int serverErrorCode; //SDC: default=0 no_setter 0056 0057 /*! 0058 @getter 0059 @return (localized) message if there was error. 0060 @setter 0061 Sets (localized) message to @a message. 0062 */ 0063 QString message; //SDC: 0064 0065 /*! 0066 @getter 0067 @return message title that sometimes is provided and prepended 0068 to the main warning/error message. Used by KDbMessageHandler. 0069 */ 0070 QString messageTitle; //SDC: 0071 0072 KDbEscapedString errorSql; //SDC: 0073 0074 KDbEscapedString sql; //SDC: 0075 0076 /*! 0077 @getter 0078 @return message from server. 0079 KDb framework offers detailed result numbers using resultCode() and detailed 0080 result i18n-ed messages using message(). These both are (almost) not engine-dependent. 0081 Use setServerMessage() to users more information on the result of operation that is 0082 non-i18n-ed and engine-specific, usually coming from the server server side. 0083 @setter 0084 Sets message from the server. 0085 */ 0086 QString serverMessage; //SDC: 0087 0088 bool serverErrorCodeSet; //SDC: default=false no_getter no_setter 0089 0090 KDbResult(int code, const QString& message); 0091 0092 explicit KDbResult(const QString& message); 0093 0094 //! @return true if there is an error i.e. a nonempty message, error code other 0095 //! than ERR_NONE or server result has been set. 0096 bool isError() const; 0097 0098 //! Sets an implementation-specific error code of server-side operation. 0099 //! Use this to give users more precise information. Implies isError() == true. 0100 //! The only way to clear already set server result code is to create a new KDbResult object. 0101 void setServerErrorCode(int errorCode); 0102 0103 //! Sets result code and prepends message to an existing message. 0104 void prependMessage(int code, const QString& message); 0105 0106 //! Prepends message to an existing message. 0107 void prependMessage(const QString& message); 0108 0109 //! Efficient clearing of the sql attribute, equivalent of setSql(QString()). 0110 inline void clearSql() { 0111 d->sql.clear(); 0112 } 0113 0114 /*! @return sql string of actually executed SQL statement, 0115 usually using drv_executeSql(). If there was error during executing SQL statement, 0116 before, that string is returned instead. */ 0117 virtual inline KDbEscapedString recentSqlString() const { 0118 return d->errorSql; 0119 } 0120 0121 protected: 0122 void init(int code, const QString& message); 0123 #if 0 0124 /*! Interactively asks a question. Console or GUI can be used for this, 0125 depending on installed message handler. For GUI version, message boxes are used. 0126 See KDbMessageHandler::askQuestion() for details. */ 0127 virtual KDbMessageHandler::ButtonCode askQuestion( 0128 KDbMessageHandler::QuestionType messageType, 0129 const QString& message, 0130 const QString &caption = QString(), 0131 KDbMessageHandler::ButtonCode defaultResult = KDbMessageHandler::Yes, 0132 const KDbGuiItem &buttonYes = KDbGuiItem(), 0133 const KDbGuiItem &buttonNo = KDbGuiItem(), 0134 const QString &dontShowAskAgainName = QString(), 0135 KDbMessageHandler::Options options = 0, 0136 KDbMessageHandler* msgHandler = 0); 0137 0138 /*! Clears number of last server operation's result stored 0139 as a single integer. Formally, this integer should be set to value 0140 that means "NO ERRORS" or "OK". This method is called by clearError(). 0141 For reimplementation. By default does nothing. 0142 @sa serverMessage() 0143 */ 0144 virtual void drv_clearServerResultCode() {} 0145 #endif 0146 }; 0147 0148 //! Interface for classes providing a result. 0149 class KDB_EXPORT KDbResultable 0150 { 0151 public: 0152 KDbResultable(); 0153 0154 KDbResultable(const KDbResultable &other); 0155 0156 KDbResultable& operator=(const KDbResultable &other); 0157 0158 virtual ~KDbResultable(); 0159 0160 KDbResult result() const; 0161 0162 void clearResult(); 0163 0164 /*! @return engine-specific last server-side operation result name, a name for KDbResult::serverErrorCode(). 0165 Use this in your application to give users more information on what's up. 0166 0167 Use this for your driver - default implementation just returns empty string. 0168 Note that this result name is not the same as the error message returned by KDbResult::serverMessage() or KDbResult::message(). 0169 @sa KDbResult::serverMessage() */ 0170 virtual QString serverResultName() const; 0171 0172 //! Sets message handler to @a handler. 0173 void setMessageHandler(KDbMessageHandler *handler); 0174 0175 //! @return associated message handler. 0 by default. 0176 KDbMessageHandler* messageHandler() const; 0177 0178 void showMessage(); 0179 0180 protected: 0181 friend class KDbMessageTitleSetter; 0182 KDbResult m_result; 0183 class Private; 0184 Private * const d; 0185 }; 0186 0187 //! Sends result @a result to debug output @a dbg. 0188 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbResult& result); 0189 0190 #endif // KDB_RESULT_H