KDb

KDbConnectionData.shared.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2015 JarosÅ‚aw Staniek <[email protected]>
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 */
35 class KDB_EXPORT KDbConnectionData //SDC: with_from_to_map operator==
36 {
37  Q_DECLARE_TR_FUNCTIONS(KDbConnectionData)
38 public:
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  */
64  QString caption; //SDC:
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  */
87  QString driverId; //SDC:
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  */
96  QString userName; //SDC:
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  - "[email protected]: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 
198 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbConnectionData::UserVisibleStringOptions)
199 
200 //! Sends information about connection data @a data to debug output @a dbg.
201 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbConnectionData& data);
202 
203 #endif
UserVisibleStringOption
Used in toUserVisibleString()
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
Database specific connection data, e.g. host, port.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Dec 7 2023 04:09:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.