KDb

KDbConnectionData.shared.h
1/* This file is part of the KDE project
2 Copyright (C) 2003-2015 Jarosław Staniek <staniek@kde.org>
3
4 This program is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this program; see the file COPYING. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KDB_CONNECTION_DATA_H
21#define KDB_CONNECTION_DATA_H
22
23#include "kdb_export.h"
24
25#include <QCoreApplication>
26#include <QDebug>
27#include <QMap>
28#include <QSharedData>
29#include <QString>
30
31/*! @brief Database specific connection data, e.g. host, port.
32
33 KDbConnection data, once configured, can be later stored for reuse.
34*/
35class KDB_EXPORT KDbConnectionData //SDC: with_from_to_map operator==
36{
37 Q_DECLARE_TR_FUNCTIONS(KDbConnectionData)
38public:
39 /*!
40 @getter
41 @return database name
42
43 Optional attribute explicitly providing database name.
44 If not empty, the database driver will attempt to use the database
45 (e.g. with "USE DATABASE" SQL statement).
46
47 For file-based database engines like SQLite, the database name is equal to filename
48 (absolute or relative) that should be open. In this case hostName and port is unused.
49
50 Can be empty, in which case if database name is required by the connection,
51 after connecting KDbConnection::useDatabase() should be called.
52 @setter
53 Explicitly sets database name.
54 */
56
57 /*!
58 @getter
59 @return caption of the connection
60 Captions are optional for identyfying given connection by name eg. for users.
61 @setter
62 Sets caption of the connection
63 */
65
66 /*!
67 @getter
68 @return additional description for the connection
69 @setter
70 Sets additional description for the connection
71 */
73
74 /*!
75 @getter
76 @return identifier of the driver.
77 ID (unique, not i18n-ed) of driver that is used (or should be used) to
78 create a connection. If you pass this KDbConnectionData object to
79 KDbDriver::createConnection() to create connection, the @a driverId member
80 will be updated with a valid KDb driver ID.
81 In other situations the @a driverId member may be used to store information what
82 driver should be used to perform connection, before we get an appropriate
83 driver object from KDbDriverManager.
84 @setter
85 Sets identifier of the driver to use
86 */
88
89 /*!
90 @getter
91 @return username used for creating connections
92 Can be empty.
93 @setter
94 Sets username used for creating connections
95 */
97
98 /*!
99 @getter
100 @return host name used for creating remote connections
101 Can be IP number. Can be empty if the connection is not remote.
102 If empty, "localhost" is used.
103 @setter
104 Sets host name used for creating remote connections
105 */
107
108 /*!
109 @getter port used for creating remote connections
110 The default is 0, what means using the database engine's default port.
111 @setter
112 Sets port used for creating remote connections
113 */
114 int port; //SDC: default=0
115
116 /*!
117 @getter
118 @return true if local socket file should be used instead of TCP/IP port.
119
120 Only meaningful for connections with localhost as server.
121 True by default, so local communication can be optimized, and users can avoid problems
122 with TCP/IP connections disabled by firewalls.
123
124 If true, @a hostName and @a port will be ignored and @a localSocketFileName() will be used.
125 On MS Windows this option is usually ignored and TCP/IP connection to the localhost is performed.
126 @setter
127 Sets flag for usage of local socket file. @see useLocalSocketFile()
128 */
129 bool useLocalSocketFile; //SDC: default=true
130
131 /*!
132 @getter
133 @return name of local (named) socket file.
134
135 For local connections only. If empty, it's driver will try to locate existing local socket
136 file. Empty by default.
137 @setter
138 Sets name of local (named) socket file
139 */
141
142 /*!
143 @getter
144 @return password used for creating connections
145
146 Can be empty string (QString("")) or null (QString()). If it is empty, empty password is passed
147 to the connection. If it is null, no password is saved and thereform no password is passed to the connection.
148 In the latter case, applications that KDb should ask for the password before performing connection
149 if password is required by the connection.
150 @setter
151 Sets password used for creating connections
152 */
154
155 /*!
156 @getter
157 @return true if the connection's password should be stored in a configuration file for later use.
158 False by default, in most cases can be set to true when non-null password is known.
159 For instance, this flag can be then shown for a user as a checkbox in the graphical interface.
160 @setter
161 Sets password-saving flag used to decide if the connection's password should be stored
162 in a configuration file for later use
163 */
164 bool savePassword; //SDC: default=false
165
166 //! Used in toUserVisibleString()
168 None = 0,
169 AddUser = 1
170 };
171 Q_DECLARE_FLAGS(UserVisibleStringOptions, UserVisibleStringOption)
172
173 /*! @return A user-visible string for the connection data
174 driverId() is used to know if driver handles server connections. If it's not possible
175 to check the driver, defaults to "file" connection.
176
177 Example strings:
178 - "myhost.org:12345" if a host and port is specified;
179 - "localhost:12345" if only a port and server-based driver is specified;
180 - "user@myhost.org:12345" if user is specified too
181 - "<file>" if a file-based driver is specified but no filename in the databaseName attribute
182 - "file: pathto/mydb.kexi" if a file-based driver is specified and filename
183 is specified in the databaseName attribute
184 - "<file>" if the driver is unknown or not specified and no databaseName is specified
185
186 User name is added if (@a options & UserVisibleStringOption::AddUser) is true (the default).
187 */
188 QString toUserVisibleString(UserVisibleStringOptions options = UserVisibleStringOption::AddUser) const;
189
190 /*! @return true if password is needed for performing connection.
191 The password has to be provided by the user.
192 @note This method needs information about driver ID; it returns false if driverId()
193 does not return a valid ID.
194 */
195 bool isPasswordNeeded() const;
196};
197
198Q_DECLARE_OPERATORS_FOR_FLAGS(KDbConnectionData::UserVisibleStringOptions)
199
200//! Sends information about connection data @a data to debug output @a dbg.
201KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbConnectionData& data);
202
203#endif
Database specific connection data, e.g. host, port.
UserVisibleStringOption
Used in toUserVisibleString()
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Wed Nov 6 2024 12:12:56 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.