File indexing completed on 2024-12-01 07:24:53

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003-2015 Jarosław Staniek <staniek@kde.org>
0003 
0004    This program is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This program is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this program; see the file COPYING.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KDB_CONNECTION_DATA_H
0021 #define KDB_CONNECTION_DATA_H
0022 
0023 #include "kdb_export.h"
0024 
0025 #include <QCoreApplication>
0026 #include <QDebug>
0027 #include <QMap>
0028 #include <QSharedData>
0029 #include <QString>
0030 
0031 /*! @brief Database specific connection data, e.g. host, port.
0032 
0033  KDbConnection data, once configured, can be later stored for reuse.
0034 */
0035 class KDB_EXPORT KDbConnectionData //SDC: with_from_to_map operator==
0036 {
0037     Q_DECLARE_TR_FUNCTIONS(KDbConnectionData)
0038 public:
0039     /*!
0040     @getter
0041     @return database name
0042 
0043     Optional attribute explicitly providing database name.
0044     If not empty, the database driver will attempt to use the database
0045     (e.g. with "USE DATABASE" SQL statement).
0046 
0047     For file-based database engines like SQLite, the database name is equal to filename
0048     (absolute or relative) that should be open. In this case hostName and port is unused.
0049 
0050     Can be empty, in which case if database name is required by the connection,
0051     after connecting KDbConnection::useDatabase() should be called.
0052     @setter
0053     Explicitly sets database name.
0054     */
0055     QString databaseName; //SDC:
0056 
0057     /*!
0058     @getter
0059     @return caption of the connection
0060     Captions are optional for identyfying given connection by name eg. for users.
0061     @setter
0062     Sets caption of the connection
0063     */
0064     QString caption; //SDC:
0065 
0066     /*!
0067     @getter
0068     @return additional description for the connection
0069     @setter
0070     Sets additional description for the connection
0071     */
0072     QString description; //SDC:
0073 
0074     /*!
0075     @getter
0076     @return identifier of the driver.
0077     ID (unique, not i18n-ed) of driver that is used (or should be used) to
0078     create a connection. If you pass this KDbConnectionData object to
0079     KDbDriver::createConnection() to create connection, the @a driverId member
0080     will be updated with a valid KDb driver ID.
0081     In other situations the @a driverId member may be used to store information what
0082     driver should be used to perform connection, before we get an appropriate
0083     driver object from KDbDriverManager.
0084     @setter
0085     Sets identifier of the driver to use
0086     */
0087     QString driverId; //SDC:
0088 
0089     /*!
0090     @getter
0091     @return username used for creating connections
0092     Can be empty.
0093     @setter
0094     Sets username used for creating connections
0095     */
0096     QString userName; //SDC:
0097 
0098     /*!
0099     @getter
0100     @return host name used for creating remote connections
0101     Can be IP number. Can be empty if the connection is not remote.
0102     If empty, "localhost" is used.
0103     @setter
0104     Sets host name used for creating remote connections
0105     */
0106     QString hostName; //SDC:
0107 
0108     /*!
0109     @getter port used for creating remote connections
0110     The default is 0, what means using the database engine's default port.
0111     @setter
0112     Sets port used for creating remote connections
0113     */
0114     int port; //SDC: default=0
0115 
0116     /*!
0117     @getter
0118     @return true if local socket file should be used instead of TCP/IP port.
0119 
0120     Only meaningful for connections with localhost as server.
0121     True by default, so local communication can be optimized, and users can avoid problems
0122     with TCP/IP connections disabled by firewalls.
0123 
0124     If true, @a hostName and @a port will be ignored and @a localSocketFileName() will be used.
0125     On MS Windows this option is usually ignored and TCP/IP connection to the localhost is performed.
0126     @setter
0127     Sets flag for usage of local socket file. @see useLocalSocketFile()
0128     */
0129     bool useLocalSocketFile; //SDC: default=true
0130 
0131     /*!
0132     @getter
0133     @return name of local (named) socket file.
0134 
0135     For local connections only. If empty, it's driver will try to locate existing local socket
0136     file. Empty by default.
0137     @setter
0138     Sets name  of local (named) socket file
0139     */
0140     QString localSocketFileName; //SDC:
0141 
0142     /*!
0143     @getter
0144     @return password used for creating connections
0145 
0146     Can be empty string (QString("")) or null (QString()). If it is empty, empty password is passed
0147     to the connection. If it is null, no password is saved and thereform no password is passed to the connection.
0148     In the latter case, applications that KDb should ask for the password before performing connection
0149     if password is required by the connection.
0150     @setter
0151     Sets password used for creating connections
0152     */
0153     QString password; //SDC:
0154 
0155     /*!
0156     @getter
0157     @return true if the connection's password should be stored in a configuration file for later use.
0158     False by default, in most cases can be set to true when non-null password is known.
0159     For instance, this flag can be then shown for a user as a checkbox in the graphical interface.
0160     @setter
0161     Sets password-saving flag used to decide if the connection's password should be stored
0162     in a configuration file for later use
0163     */
0164     bool savePassword; //SDC: default=false
0165 
0166     //! Used in toUserVisibleString()
0167     enum class UserVisibleStringOption {
0168         None = 0,
0169         AddUser = 1
0170     };
0171     Q_DECLARE_FLAGS(UserVisibleStringOptions, UserVisibleStringOption)
0172 
0173     /*! @return A user-visible string for the connection data
0174     driverId() is used to know if driver handles server connections. If it's not possible
0175     to check the driver, defaults to "file" connection.
0176 
0177     Example strings:
0178      - "myhost.org:12345" if a host and port is specified;
0179      - "localhost:12345" if only a port and server-based driver is specified;
0180      - "user@myhost.org:12345" if user is specified too
0181      - "<file>" if a file-based driver is specified but no filename in the databaseName attribute
0182      - "file: pathto/mydb.kexi" if a file-based driver is specified and filename
0183        is specified in the databaseName attribute
0184      - "<file>" if the driver is unknown or not specified and no databaseName is specified
0185 
0186      User name is added if (@a options & UserVisibleStringOption::AddUser) is true (the default).
0187     */
0188     QString toUserVisibleString(UserVisibleStringOptions options = UserVisibleStringOption::AddUser) const;
0189 
0190     /*! @return true if password is needed for performing connection.
0191     The password has to be provided by the user.
0192     @note This method needs information about driver ID; it returns false if driverId()
0193           does not return a valid ID.
0194     */
0195     bool isPasswordNeeded() const;
0196 };
0197 
0198 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbConnectionData::UserVisibleStringOptions)
0199 
0200 //! Sends information about connection data @a data to debug output @a dbg.
0201 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbConnectionData& data);
0202 
0203 #endif