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