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