source: trunk/doc/html/qsqldriver.html@ 190

Last change on this file since 190 was 190, checked in by rudi, 14 years ago

reference documentation added

File size: 17.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/sql/qsqldriver.cpp:52 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QSqlDriver Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSqlDriver Class Reference<br><small>[<a href="sql.html">sql module</a>]</small></h1>
33
34<p>The QSqlDriver class is an abstract base class for accessing
35SQL databases.
36<a href="#details">More...</a>
37<p><tt>#include &lt;<a href="qsqldriver-h.html">qsqldriver.h</a>&gt;</tt>
38<p>Inherits <a href="qobject.html">QObject</a>.
39<p><a href="qsqldriver-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn>enum <a href="#DriverFeature-enum"><b>DriverFeature</b></a> { Transactions, QuerySize, BLOB, Unicode, PreparedQueries, NamedPlaceholders, PositionalPlaceholders }</li>
43<li class=fn><a href="#QSqlDriver"><b>QSqlDriver</b></a> ( QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
44<li class=fn><a href="#~QSqlDriver"><b>~QSqlDriver</b></a> ()</li>
45<li class=fn>bool <a href="#isOpen"><b>isOpen</b></a> () const</li>
46<li class=fn>bool <a href="#isOpenError"><b>isOpenError</b></a> () const</li>
47<li class=fn>virtual bool <a href="#beginTransaction"><b>beginTransaction</b></a> ()</li>
48<li class=fn>virtual bool <a href="#commitTransaction"><b>commitTransaction</b></a> ()</li>
49<li class=fn>virtual bool <a href="#rollbackTransaction"><b>rollbackTransaction</b></a> ()</li>
50<li class=fn>virtual QStringList <a href="#tables"><b>tables</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tableType ) const</li>
51<li class=fn>virtual QSqlIndex <a href="#primaryIndex"><b>primaryIndex</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tableName ) const</li>
52<li class=fn>virtual QSqlRecord <a href="#record"><b>record</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tableName ) const</li>
53<li class=fn>virtual QSqlRecord <a href="#record-2"><b>record</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;query ) const</li>
54<li class=fn>virtual QSqlRecordInfo <a href="#recordInfo"><b>recordInfo</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tablename ) const</li>
55<li class=fn>virtual QSqlRecordInfo <a href="#recordInfo-2"><b>recordInfo</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;query ) const</li>
56<li class=fn>virtual QString <a href="#nullText"><b>nullText</b></a> () const</li>
57<li class=fn>virtual QString <a href="#formatValue"><b>formatValue</b></a> ( const&nbsp;QSqlField&nbsp;*&nbsp;field, bool&nbsp;trimStrings = FALSE ) const</li>
58<li class=fn>QSqlError <a href="#lastError"><b>lastError</b></a> () const</li>
59<li class=fn>virtual bool <a href="#hasFeature"><b>hasFeature</b></a> ( DriverFeature&nbsp;f ) const = 0</li>
60<li class=fn>virtual bool <a href="#open"><b>open</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;db, const&nbsp;QString&nbsp;&amp;&nbsp;user = QString::null, const&nbsp;QString&nbsp;&amp;&nbsp;password = QString::null, const&nbsp;QString&nbsp;&amp;&nbsp;host = QString::null, int&nbsp;port = -1 ) = 0</li>
61<li class=fn>virtual void <a href="#close"><b>close</b></a> () = 0</li>
62<li class=fn>virtual QSqlQuery <a href="#createQuery"><b>createQuery</b></a> () const = 0</li>
63<li class=fn>bool <a href="#open-2"><b>open</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;db, const&nbsp;QString&nbsp;&amp;&nbsp;user, const&nbsp;QString&nbsp;&amp;&nbsp;password, const&nbsp;QString&nbsp;&amp;&nbsp;host, int&nbsp;port, const&nbsp;QString&nbsp;&amp;&nbsp;connOpts )</li>
64</ul>
65<h2>Protected Members</h2>
66<ul>
67<li class=fn>virtual void <a href="#setOpen"><b>setOpen</b></a> ( bool&nbsp;o )</li>
68<li class=fn>virtual void <a href="#setOpenError"><b>setOpenError</b></a> ( bool&nbsp;e )</li>
69<li class=fn>virtual void <a href="#setLastError"><b>setLastError</b></a> ( const&nbsp;QSqlError&nbsp;&amp;&nbsp;e )</li>
70</ul>
71<hr><a name="details"></a><h2>Detailed Description</h2>
72
73
74The QSqlDriver class is an abstract base class for accessing
75SQL databases.
76<p>
77
78<p> This class should not be used directly. Use <a href="qsqldatabase.html">QSqlDatabase</a> instead.
79<p>See also <a href="database.html">Database Classes</a>.
80
81<hr><h2>Member Type Documentation</h2>
82<h3 class=fn><a name="DriverFeature-enum"></a>QSqlDriver::DriverFeature</h3>
83
84<p> This enum contains a list of features a driver may support. Use
85<a href="#hasFeature">hasFeature</a>() to query whether a feature is supported or not.
86<ul>
87<li><tt>QSqlDriver::Transactions</tt> - whether the driver supports SQL transactions
88<li><tt>QSqlDriver::QuerySize</tt> - whether the database is capable of reporting the size
89of a query. Note that some databases do not support returning the size
90(i.e. number of rows returned) of a query, in which case
91<a href="qsqlquery.html#size">QSqlQuery::size</a>() will return -1
92<li><tt>QSqlDriver::BLOB</tt> - whether the driver supports Binary Large Object fields
93<li><tt>QSqlDriver::Unicode</tt> - whether the driver supports Unicode strings if the
94database server does
95<li><tt>QSqlDriver::PreparedQueries</tt> - whether the driver supports prepared query execution
96<li><tt>QSqlDriver::NamedPlaceholders</tt> - whether the driver supports usage of named placeholders
97<li><tt>QSqlDriver::PositionalPlaceholders</tt> - whether the driver supports usage of positional placeholders
98</ul><p> More information about supported features can be found in the
99<a href="sql-driver.html">Qt SQL driver</a> documentation.
100<p> <p>See also <a href="#hasFeature">hasFeature</a>().
101
102<hr><h2>Member Function Documentation</h2>
103<h3 class=fn><a name="QSqlDriver"></a>QSqlDriver::QSqlDriver ( <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
104</h3>
105Default constructor. Creates a new driver with parent <em>parent</em>,
106called <em>name</em>.
107<p>
108<h3 class=fn><a name="~QSqlDriver"></a>QSqlDriver::~QSqlDriver ()
109</h3>
110Destroys the object and frees any allocated resources.
111
112<h3 class=fn>bool <a name="beginTransaction"></a>QSqlDriver::beginTransaction ()<tt> [virtual]</tt>
113</h3>
114Protected function which derived classes can reimplement to begin
115a transaction. If successful, return TRUE, otherwise return FALSE.
116The default implementation returns FALSE.
117<p> <p>See also <a href="#commitTransaction">commitTransaction</a>() and <a href="#rollbackTransaction">rollbackTransaction</a>().
118
119<h3 class=fn>void <a name="close"></a>QSqlDriver::close ()<tt> [pure virtual]</tt>
120</h3>
121
122<p> Derived classes must reimplement this abstract virtual function in
123order to close the database connection. Return TRUE on success,
124FALSE on failure.
125<p> <p>See also <a href="#setOpen">setOpen</a>().
126
127<p>
128<h3 class=fn>bool <a name="commitTransaction"></a>QSqlDriver::commitTransaction ()<tt> [virtual]</tt>
129</h3>
130Protected function which derived classes can reimplement to commit
131a transaction. If successful, return TRUE, otherwise return FALSE.
132The default implementation returns FALSE.
133<p> <p>See also <a href="#beginTransaction">beginTransaction</a>() and <a href="#rollbackTransaction">rollbackTransaction</a>().
134
135<h3 class=fn><a href="qsqlquery.html">QSqlQuery</a> <a name="createQuery"></a>QSqlDriver::createQuery () const<tt> [pure virtual]</tt>
136</h3>
137
138<p> Creates an empty SQL result on the database. Derived classes must
139reimplement this function and return a <a href="qsqlquery.html">QSqlQuery</a> object
140appropriate for their database to the caller.
141<p>
142<h3 class=fn><a href="qstring.html">QString</a> <a name="formatValue"></a>QSqlDriver::formatValue ( const&nbsp;<a href="qsqlfield.html">QSqlField</a>&nbsp;*&nbsp;field, bool&nbsp;trimStrings = FALSE ) const<tt> [virtual]</tt>
143</h3>
144Returns a string representation of the <em>field</em> value for the
145database. This is used, for example, when constructing INSERT and
146UPDATE statements.
147<p> The default implementation returns the value formatted as a string
148according to the following rules:
149<p> <ul>
150<p> <li> If <em>field</em> is NULL, <a href="#nullText">nullText</a>() is returned.
151<p> <li> If <em>field</em> is character data, the value is returned enclosed
152in single quotation marks, which is appropriate for many SQL
153databases. Any embedded single-quote characters are escaped
154(replaced with two single-quote characters). If <em>trimStrings</em> is
155TRUE (the default is FALSE), all trailing whitespace is trimmed
156from the field.
157<p> <li> If <em>field</em> is date/time data, the value is formatted in ISO
158format and enclosed in single quotation marks. If the date/time
159data is invalid, nullText() is returned.
160<p> <li> If <em>field</em> is bytearray data, and the driver can edit binary
161fields, the value is formatted as a hexadecimal string.
162<p> <li> For any other field type toString() will be called on its value
163and the result returned.
164<p> </ul>
165<p> <p>See also <a href="qvariant.html#toString">QVariant::toString</a>().
166
167<p>
168<h3 class=fn>bool <a name="hasFeature"></a>QSqlDriver::hasFeature ( <a href="qsqldriver.html#DriverFeature-enum">DriverFeature</a>&nbsp;f ) const<tt> [pure virtual]</tt>
169</h3>
170
171<p> Returns TRUE if the driver supports feature <em>f</em>; otherwise
172returns FALSE.
173<p> Note that some databases need to be <a href="#open">open</a>() before this can be
174determined.
175<p> <p>See also <a href="#DriverFeature-enum">DriverFeature</a>.
176
177<h3 class=fn>bool <a name="isOpen"></a>QSqlDriver::isOpen () const
178</h3>
179Returns TRUE if the database connection is open; otherwise returns
180FALSE.
181
182<h3 class=fn>bool <a name="isOpenError"></a>QSqlDriver::isOpenError () const
183</h3>
184Returns TRUE if the there was an error opening the database
185connection; otherwise returns FALSE.
186
187<h3 class=fn><a href="qsqlerror.html">QSqlError</a> <a name="lastError"></a>QSqlDriver::lastError () const
188</h3>
189Returns a <a href="qsqlerror.html">QSqlError</a> object which contains information about the
190last error that occurred on the database.
191
192<h3 class=fn><a href="qstring.html">QString</a> <a name="nullText"></a>QSqlDriver::nullText () const<tt> [virtual]</tt>
193</h3>
194Returns a string representation of the NULL value for the
195database. This is used, for example, when constructing INSERT and
196UPDATE statements. The default implementation returns the string
197"NULL".
198
199<h3 class=fn>bool <a name="open"></a>QSqlDriver::open ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;db, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;user = QString::null, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;password = QString::null, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;host = QString::null, int&nbsp;port = -1 )<tt> [pure virtual]</tt>
200</h3>
201
202<p> Derived classes must reimplement this abstract virtual function in
203order to open a database connection on database <em>db</em>, using user
204name <em>user</em>, password <em>password</em>, host <em>host</em> and port <em>port</em>.
205<p> The function <em>must</em> return TRUE on success and FALSE on failure.
206<p> <p>See also <a href="#setOpen">setOpen</a>().
207
208<p>
209<h3 class=fn>bool <a name="open-2"></a>QSqlDriver::open ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;db, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;user, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;password, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;host, int&nbsp;port, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connOpts )
210</h3>
211This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
212<p> Open a database connection on database <em>db</em>, using user name <em>user</em>, password <em>password</em>, host <em>host</em>, port <em>port</em> and
213connection options <em>connOpts</em>.
214<p> Returns TRUE on success and FALSE on failure.
215<p> <p>See also <a href="#setOpen">setOpen</a>().
216
217<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="primaryIndex"></a>QSqlDriver::primaryIndex ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tableName ) const<tt> [virtual]</tt>
218</h3>
219Returns the primary index for table <em>tableName</em>. Returns an empty
220<a href="qsqlindex.html">QSqlIndex</a> if the table doesn't have a primary index. The default
221implementation returns an empty index.
222
223<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a> <a name="record"></a>QSqlDriver::record ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tableName ) const<tt> [virtual]</tt>
224</h3>
225Returns a <a href="qsqlrecord.html">QSqlRecord</a> populated with the names of the fields in
226table <em>tableName</em>. If no such table exists, an empty record is
227returned. The default implementation returns an empty record.
228
229<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a> <a name="record-2"></a>QSqlDriver::record ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;query ) const<tt> [virtual]</tt>
230</h3>
231This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
232<p> Returns a <a href="qsqlrecord.html">QSqlRecord</a> populated with the names of the fields in the
233SQL <em>query</em>. The default implementation returns an empty record.
234
235<h3 class=fn><a href="qsqlrecordinfo.html">QSqlRecordInfo</a> <a name="recordInfo"></a>QSqlDriver::recordInfo ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tablename ) const<tt> [virtual]</tt>
236</h3>
237Returns a <a href="qsqlrecordinfo.html">QSqlRecordInfo</a> object with meta data about the table <em>tablename</em>.
238
239<h3 class=fn><a href="qsqlrecordinfo.html">QSqlRecordInfo</a> <a name="recordInfo-2"></a>QSqlDriver::recordInfo ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;query ) const<tt> [virtual]</tt>
240</h3>
241This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
242<p> Returns a <a href="qsqlrecordinfo.html">QSqlRecordInfo</a> object with meta data for the <a href="qsqlquery.html">QSqlQuery</a>
243<em>query</em>. Note that this overloaded function may return less
244information than the <a href="#recordInfo">recordInfo</a>() function which takes the name of
245a table as parameter.
246
247<h3 class=fn>bool <a name="rollbackTransaction"></a>QSqlDriver::rollbackTransaction ()<tt> [virtual]</tt>
248</h3>
249Protected function which derived classes can reimplement to
250rollback a transaction. If successful, return TRUE, otherwise
251return FALSE. The default implementation returns FALSE.
252<p> <p>See also <a href="#beginTransaction">beginTransaction</a>() and <a href="#commitTransaction">commitTransaction</a>().
253
254<h3 class=fn>void <a name="setLastError"></a>QSqlDriver::setLastError ( const&nbsp;<a href="qsqlerror.html">QSqlError</a>&nbsp;&amp;&nbsp;e )<tt> [virtual protected]</tt>
255</h3>
256Protected function which allows derived classes to set the value
257of the last error, <em>e</em>, that occurred on the database.
258<p> <p>See also <a href="#lastError">lastError</a>().
259
260<h3 class=fn>void <a name="setOpen"></a>QSqlDriver::setOpen ( bool&nbsp;o )<tt> [virtual protected]</tt>
261</h3>
262Protected function which sets the open state of the database to <em>o</em>. Derived classes can use this function to report the status of
263<a href="#open">open</a>().
264<p> <p>See also <a href="#open">open</a>() and <a href="#setOpenError">setOpenError</a>().
265
266<h3 class=fn>void <a name="setOpenError"></a>QSqlDriver::setOpenError ( bool&nbsp;e )<tt> [virtual protected]</tt>
267</h3>
268Protected function which sets the open error state of the database
269to <em>e</em>. Derived classes can use this function to report the
270status of <a href="#open">open</a>(). Note that if <em>e</em> is TRUE the open state of the
271database is set to closed (i.e. <a href="#isOpen">isOpen</a>() returns FALSE).
272<p> <p>See also <a href="#open">open</a>().
273
274<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="tables"></a>QSqlDriver::tables ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tableType ) const<tt> [virtual]</tt>
275</h3>
276Returns a list of tables in the database. The default
277implementation returns an empty list.
278<p> The <em>tableType</em> argument describes what types of tables
279should be returned. Due to binary compatibility, the string
280contains the value of the enum QSql::TableTypes as text.
281An empty string should be treated as QSql::Tables for
282downward compatibility.
283<p> <p>See also <a href="qsql.html#TableType-enum">QSql::TableType</a>.
284
285<!-- eof -->
286<hr><p>
287This file is part of the <a href="index.html">Qt toolkit</a>.
288Copyright &copy; 1995-2007
289<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
290<table width=100% cellspacing=0 border=0><tr>
291<td>Copyright &copy; 2007
292<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
293<td align=right><div align=right>Qt 3.3.8</div>
294</table></div></address></body>
295</html>
Note: See TracBrowser for help on using the repository browser.