1.1 --- a/epoc32/include/d32dbms.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/d32dbms.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1485 @@
1.4 -d32dbms.h
1.5 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#if !defined(__D32DBMS_H__)
1.21 +#define __D32DBMS_H__
1.22 +
1.23 +#ifndef __S32STD_H__
1.24 +#include <s32std.h>
1.25 +#endif
1.26 +#ifndef __F32FILE_H__
1.27 +#include <f32file.h>
1.28 +#endif
1.29 +
1.30 +// other classes referenced
1.31 +class RFs;
1.32 +class CDbObject;
1.33 +class CDbRowConstraint;
1.34 +class CDbCursor;
1.35 +class CDbDatabase;
1.36 +class CDbIncremental;
1.37 +class CDbNotifier;
1.38 +class TDbColumn;
1.39 +class TDbColumnC;
1.40 +
1.41 +// classes defined
1.42 +class TDbCol;
1.43 +class CDbColSet;
1.44 +class TDbColSetIter;
1.45 +class TDbKeyCol;
1.46 +class CDbKey;
1.47 +class TDbBookmark;
1.48 +class TDbQuery;
1.49 +class RDbHandleBase;
1.50 +template<class T> class RDbHandle;
1.51 +class RDbRowConstraint;
1.52 +class RDbRowSet;
1.53 +class RDbColReadStream;
1.54 +class RDbColWriteStream;
1.55 +class TDbWindow;
1.56 +class RDbView;
1.57 +template<class T> class TUnion;
1.58 +class TDbLookupKey;
1.59 +class TDbSeekKey;
1.60 +template<TInt S> class TDbSeekMultiKey;
1.61 +class RDbTable;
1.62 +class CDbNames;
1.63 +class RDbDatabase;
1.64 +class RDbIncremental;
1.65 +class RDbUpdate;
1.66 +class RDbNotifier;
1.67 +class RDbs;
1.68 +class RDbNamedDatabase;
1.69 +class RDbStoreDatabase;
1.70 +
1.71 +/**
1.72 +The maximum length for a DBMS name: 64 characters.
1.73 +@publishedAll
1.74 +@released
1.75 +*/
1.76 +const TInt KDbMaxName=0x40;
1.77 +
1.78 +/**
1.79 +The maximum length for a DBMS column name: 64 characters.
1.80 +@publishedAll
1.81 +@released
1.82 +*/
1.83 +const TInt KDbMaxColName=KDbMaxName;
1.84 +
1.85 +/**
1.86 +Represents a writable DBMS name. It maps to a modifiable buffer descriptor
1.87 +with maximum size KDbMaxName.
1.88 +
1.89 +Notes:
1.90 +
1.91 +A DBMS name must begin with an alphabetic character, after which any alphabetic,
1.92 +numeric or the _ (underscore) character may be used. DBMS names are also limited
1.93 +to 64 characters in length.
1.94 +
1.95 +Table names must be unique within a database, and columns and indexes must
1.96 +have unique names within the table to which they belong. For the purposes
1.97 +of uniqueness and identification, the names are folded before comparison,
1.98 +so two columns named column_one and Column_ONE are considered to have the
1.99 +same name.
1.100 +
1.101 +@see TBuf
1.102 +@publishedAll
1.103 +@released
1.104 +*/
1.105 +typedef TBuf<KDbMaxName> TDbName;
1.106 +
1.107 +/** Represents a non-writeable DBMS name. It maps to a non modifiable buffer descriptor
1.108 +with maximum size KDbMaxName.
1.109 +
1.110 +Notes:
1.111 +
1.112 +A DBMS name must begin with an alphabetic character, after which any alphabetic,
1.113 +numeric or the _ (underscore) character may be used. DBMS names are also limited
1.114 +to 64 characters in length.
1.115 +
1.116 +Table names must be unique within a database, and columns and indexes must
1.117 +have unique names within the table to which they belong. For the purposes
1.118 +of uniqueness and identification, the names are folded before comparison,
1.119 +so two columns named column_one and Column_ONE are considered to have the
1.120 +same name.
1.121 +
1.122 +@see TBufC
1.123 +@publishedAll
1.124 +@released
1.125 +*/
1.126 +typedef TBufC<KDbMaxName> TDbNameC;
1.127 +
1.128 +/** Represents a writable DBMS column name. It maps to a modifiable buffer descriptor
1.129 +with maximum size KDbMaxColName.
1.130 +
1.131 +Notes:
1.132 +
1.133 +A DBMS name must begin with an alphabetic character, after which any alphabetic,
1.134 +numeric or the _ (underscore) character may be used. DBMS names are also limited
1.135 +to 64 characters in length.
1.136 +
1.137 +Table names must be unique within a database, and columns and indexes must
1.138 +have unique names within the table to which they belong. For the purposes
1.139 +of uniqueness and identification, the names are folded before comparison,
1.140 +so two columns named column_one and Column_ONE are considered to have the
1.141 +same name.
1.142 +@publishedAll
1.143 +@released
1.144 +*/
1.145 +typedef TBuf<KDbMaxColName> TDbColName;
1.146 +
1.147 +/** Represents a non-writable DBMS column name. It maps to a non-modifiable buffer
1.148 +descriptor with maximum size KDbMaxColName.
1.149 +
1.150 +Notes:
1.151 +
1.152 +A DBMS name must begin with an alphabetic character, after which any alphabetic,
1.153 +numeric or the _ (underscore) character may be used. DBMS names are also limited
1.154 +to 64 characters in length.
1.155 +
1.156 +Table names must be unique within a database, and columns and indexes must
1.157 +have unique names within the table to which they belong. For the purposes
1.158 +of uniqueness and identification, the names are folded before comparison,
1.159 +so two columns named column_one and Column_ONE are considered to have the
1.160 +same name.
1.161 +
1.162 +@see TBufC
1.163 +@publishedAll
1.164 +@released
1.165 +*/
1.166 +typedef TBufC<KDbMaxColName> TDbColNameC;
1.167 +
1.168 +/** Specifies when DBMS objects require a column ordinal to identify a column in
1.169 +a column set or in a rowset.
1.170 +
1.171 +Note that KDbNullColNo is a special value of TDbColNo used to indicate that
1.172 +no such column exists.
1.173 +@publishedAll
1.174 +@released
1.175 +*/
1.176 +typedef TInt TDbColNo;
1.177 +
1.178 +/**
1.179 +Indicates that a specified column does not exist.
1.180 +@publishedAll
1.181 +@released
1.182 +*/
1.183 +const TDbColNo KDbNullColNo=0;
1.184 +
1.185 +/**
1.186 +A value returned by RDbRowSet::Count() when the number of rows cannot be determined.
1.187 +
1.188 +@see RDbRowSet
1.189 +@publishedAll
1.190 +@released
1.191 +*/
1.192 +const TInt KDbUndefinedCount=-1;
1.193 +
1.194 +/**
1.195 +The length of a column is undefined.
1.196 +@publishedAll
1.197 +@released
1.198 +*/
1.199 +const TInt KDbUndefinedLength=-1;
1.200 +
1.201 +/**
1.202 +The default text column length. This is equal to 50.
1.203 +@publishedAll
1.204 +@released
1.205 +*/
1.206 +const TInt KDbDefaultTextColLength=50;
1.207 +
1.208 +/**
1.209 +Represents every supported column type.
1.210 +@publishedAll
1.211 +@released
1.212 +*/
1.213 +enum TDbColType
1.214 + {
1.215 + /** The column stores a single bit.
1.216 +
1.217 + Representation range: 0 to 1
1.218 +
1.219 + Storage: 1 bit
1.220 +
1.221 + Auto-increment: Yes
1.222 +
1.223 + Index key: Yes */
1.224 + EDbColBit,
1.225 +
1.226 + /** The column stores an 8-bit signed integer.
1.227 +
1.228 + Representation range: -2^7 to 2^7 - 1
1.229 +
1.230 + Storage: 1 byte
1.231 +
1.232 + Auto-increment: Yes
1.233 +
1.234 + Index key: Yes */
1.235 + EDbColInt8,
1.236 +
1.237 + /** The column stores an 8-bit unsigned integer.
1.238 +
1.239 + Representation range: 0 to 2^8-1
1.240 +
1.241 + Storage: 1 byte
1.242 +
1.243 + Auto-increment: Yes
1.244 +
1.245 + Index key: Yes */
1.246 + EDbColUint8,
1.247 +
1.248 + /** The column stores a 16-bit signed integer.
1.249 +
1.250 + Representation range: -2^15 to 2^15 - 1
1.251 +
1.252 + Storage: 2 bytes
1.253 +
1.254 + Auto-increment: Yes
1.255 +
1.256 + Index key: Yes */
1.257 + EDbColInt16,
1.258 +
1.259 + /** The column stores a 16-bit unsigned integer.
1.260 +
1.261 + Representation range: 0 to 2^16-1
1.262 +
1.263 + Storage: 2 bytes
1.264 +
1.265 + Auto-increment: Yes
1.266 +
1.267 + Index key: Yes */
1.268 + EDbColUint16,
1.269 +
1.270 + /** The column stores a 32-bit signed integer.
1.271 +
1.272 + Representation range: -2^31 to 2^31 - 1
1.273 +
1.274 + Storage: 4 bytes
1.275 +
1.276 + Auto-increment: Yes
1.277 +
1.278 + Index key: Yes */
1.279 + EDbColInt32,
1.280 +
1.281 + /** The column stores a 32-bit unsigned integer.
1.282 +
1.283 + Representation range: 0 to 2^32-1
1.284 +
1.285 + Storage: 4 bytes
1.286 +
1.287 + Auto-increment: Yes
1.288 +
1.289 + Index key: Yes */
1.290 + EDbColUint32,
1.291 +
1.292 + /** The column stores a 64-bit signed integer.
1.293 +
1.294 + Representation range: -2^63 to 2^63 - 1
1.295 +
1.296 + Storage: 8 bytes
1.297 +
1.298 + Auto-increment: No
1.299 +
1.300 + Index key: Yes */
1.301 + EDbColInt64,
1.302 +
1.303 + /** The column stores a 32-bit floating point value.
1.304 +
1.305 + Representation range: 1.4 X 10^-45 to 3.40282 X 10^38
1.306 +
1.307 + Storage: 4 bytes
1.308 +
1.309 + Auto-increment: No
1.310 +
1.311 + Index key: Yes */
1.312 + EDbColReal32,
1.313 +
1.314 + /** The column stores a 64-bit floating point value.
1.315 +
1.316 + Representation range: 2.2 X 10^-308 to 1.79769 X 10^308
1.317 +
1.318 + Storage: 8 bytes
1.319 +
1.320 + Auto-increment: No
1.321 +
1.322 + Index key: Yes */
1.323 + EDbColReal64,
1.324 +
1.325 + /** The column stores a date/time value.
1.326 +
1.327 + Representation range: 1/1/0 to 31/12/9999
1.328 +
1.329 + Storage: 8 bytes
1.330 +
1.331 + Auto-increment: No
1.332 +
1.333 + Index key: Yes */
1.334 + EDbColDateTime,
1.335 +
1.336 + /** The column stores a (short) variable length of non-Unicode text data.
1.337 +
1.338 + Representation range: 0 to 256 characters
1.339 +
1.340 + Storage: 0 to 256 bytes
1.341 +
1.342 + Auto-increment: No
1.343 +
1.344 + Index key: Yes */
1.345 + EDbColText8,
1.346 +
1.347 + /** The column stores a (short) variable length of Unicode text data.
1.348 +
1.349 + Representation range: 0 to 256 characters
1.350 +
1.351 + Storage: 0 to 512 bytes
1.352 +
1.353 + Auto-increment: No
1.354 +
1.355 + Index key: Yes */
1.356 + EDbColText16,
1.357 +
1.358 + /** The column stores a (short) variable length of untyped data.
1.359 +
1.360 + Representation range: 0 to 255 bytes
1.361 +
1.362 + Storage: 0 to 256 bytes
1.363 +
1.364 + Auto-increment: No
1.365 +
1.366 + Index key: No */
1.367 + EDbColBinary,
1.368 +
1.369 + /** The column stores a potentially large amount of non-Unicode text data.
1.370 +
1.371 + Representation range: 0 to 2^31 characters
1.372 +
1.373 + Storage: 0 to 2 Gbytes
1.374 +
1.375 + Auto-increment: No
1.376 +
1.377 + Index key: Truncated */
1.378 + EDbColLongText8,
1.379 +
1.380 + /** The column stores a potentially large amount of Unicode text data.
1.381 +
1.382 + Representation range: 0 to 2^30 characters
1.383 +
1.384 + Storage: 0 to 2 Gbytes
1.385 +
1.386 + Auto-increment: No
1.387 +
1.388 + Index key: Truncated */
1.389 + EDbColLongText16,
1.390 +
1.391 + /** The column stores a potentially large amount of untyped data.
1.392 +
1.393 + Representation range: 0 to 2^31 bytes
1.394 +
1.395 + Storage: 0 to 2 Gbytes
1.396 +
1.397 + Auto-increment: No
1.398 +
1.399 + Index key: No */
1.400 + EDbColLongBinary,
1.401 +
1.402 + /** This is equivalent to EDbColText8 if the build is narrow, and
1.403 + EDbColText16 if the build is Unicode. */
1.404 + EDbColText=EDbColText16,
1.405 +
1.406 + /** This is equivalent to EDbColLongText8 if the build is narrow, and
1.407 + EDbColLongText16 if the build is Unicode. */
1.408 + EDbColLongText=EDbColLongText16
1.409 + };
1.410 +
1.411 +/**
1.412 +Represents different ways of comparing Text and LongText columns.
1.413 +
1.414 +This affects the ordering of indexes (see CDbKey), the evaluation of SQL
1.415 +queries and matching row constraints (see TDbQuery).
1.416 +@publishedAll
1.417 +@released
1.418 +*/
1.419 +enum TDbTextComparison
1.420 + {
1.421 + /** Use standard text comparison and ordering. */
1.422 + EDbCompareNormal,
1.423 + /** Use folded text for comparison and ordering. */
1.424 + EDbCompareFolded,
1.425 + /** Use collation for comparison and ordering. */
1.426 + EDbCompareCollated
1.427 + };
1.428 +
1.429 +/**
1.430 +Defines a column in a table or rowset.
1.431 +
1.432 +The data members are public because this is really a structure to group the
1.433 +attributes of the column together.
1.434 +
1.435 +Three non-default constructors are provided for convenience.
1.436 +@publishedAll
1.437 +@released
1.438 +*/
1.439 +class TDbCol
1.440 + {
1.441 + friend class CDbColSet;
1.442 +public:
1.443 + enum {ENotNull=0x01,EAutoIncrement=0x02};
1.444 +public:
1.445 + /** Constructs an uninitialised TDbCol. It is necessary because there are
1.446 + also non-default constructors in this class. */
1.447 + inline TDbCol() {}
1.448 + inline TDbCol(const TDbCol&);
1.449 + inline TDbCol& operator=(const TDbCol&);
1.450 + IMPORT_C TDbCol(const TDesC& aName,TDbColType aType);
1.451 + IMPORT_C TDbCol(const TDesC& aName,TDbColType aType,TInt aMaxLength);
1.452 + static inline TBool IsLong(TDbColType aType);
1.453 +private:
1.454 + inline TDbCol(const TDesC& aName);
1.455 +public:
1.456 + /** The column type. */
1.457 + TDbColType iType;
1.458 + /** The maximum length of data that can be stored in a Text or Binary
1.459 + column. */
1.460 + TInt iMaxLength;
1.461 + /** A set of flags describing other column attributes. This must be one
1.462 + of the anonymous enum values ENotNull or EAutoIncrement. */
1.463 + TUint iAttributes;
1.464 + /** The column name. */
1.465 + TDbColNameC iName;
1.466 + };
1.467 +
1.468 +/** Manages a set of column definitions which describe a table or rowset
1.469 +structure. Column definitions can be added and removed. The set can be
1.470 +iterated over, and ordinals for a column can be looked up.
1.471 +
1.472 +The class is not intended for user derivation.
1.473 +@publishedAll
1.474 +@released
1.475 +*/
1.476 +class CDbColSet : public CBase
1.477 + {
1.478 + friend class TDbColSetIter;
1.479 +public:
1.480 + IMPORT_C CDbColSet();
1.481 + IMPORT_C static CDbColSet* NewL();
1.482 + IMPORT_C static CDbColSet* NewLC();
1.483 + IMPORT_C ~CDbColSet();
1.484 + inline const TDbCol& operator[](TDbColNo aCol) const;
1.485 + IMPORT_C const TDbCol* Col(const TDesC& aColName) const;
1.486 + IMPORT_C TDbColNo ColNo(const TDesC& aColName) const;
1.487 + inline TInt Count() const;
1.488 + inline void Clear();
1.489 + IMPORT_C CDbColSet& AddL(const TDbCol& aCol);
1.490 + IMPORT_C void Remove(const TDesC& aColName);
1.491 +private:
1.492 + CArrayPakFlat<TDbCol> iColumns;
1.493 + };
1.494 +
1.495 +/**
1.496 +Provides a useful way to iterate over the contents of a column set.
1.497 +@publishedAll
1.498 +@released
1.499 +*/
1.500 +class TDbColSetIter
1.501 + {
1.502 +public:
1.503 + IMPORT_C TDbColSetIter(const CDbColSet& aColSet);
1.504 + inline operator TAny* () const;
1.505 + inline const TDbCol& operator*() const;
1.506 + inline const TDbCol* operator->() const;
1.507 + IMPORT_C TDbColSetIter& operator++();
1.508 + inline TDbColSetIter operator++(TInt);
1.509 + inline TDbColNo Col() const;
1.510 +private:
1.511 + const TDbCol* iColumn;
1.512 + TInt iIndex;
1.513 + const CArrayPakFlat<TDbCol>* iArray;
1.514 + };
1.515 +
1.516 +/** Defines a key column in an index.
1.517 +
1.518 +The data members are public as this is really a structure to group the
1.519 +attributes of the key column together. Two non-default constructors are
1.520 +provided for convenience.
1.521 +@publishedAll
1.522 +@released
1.523 +*/
1.524 +class TDbKeyCol
1.525 + {
1.526 +public:
1.527 + /** Specifies whether a key column in an index should be sorted in
1.528 + ascending or descending order. */
1.529 + enum TOrder
1.530 + {
1.531 + /** Use ascending order. */
1.532 + EAsc,
1.533 + /** Use descending order. */
1.534 + EDesc
1.535 + };
1.536 +public:
1.537 + /** Constructs an uninitialised object. Default constructor. It is necessary
1.538 + because there are also non-default constructors in this class. */
1.539 + inline TDbKeyCol() {}
1.540 + inline TDbKeyCol(const TDbKeyCol&);
1.541 + inline TDbKeyCol& operator=(const TDbKeyCol&);
1.542 + IMPORT_C TDbKeyCol(const TDesC& aName,TOrder anOrder=EAsc);
1.543 + IMPORT_C TDbKeyCol(const TDesC& aName,TInt aLength,TOrder anOrder=EAsc);
1.544 +public:
1.545 + /** The ordering of the key. */
1.546 + TOrder iOrder;
1.547 + /** The maximum number of characters used to index Text or LongText
1.548 + columns. If equal to KDbUndefinedLength (the default), all the characters
1.549 + in the defined column will be used. */
1.550 + TInt iLength;
1.551 + /** The column name for the key. */
1.552 + TDbColNameC iName;
1.553 + };
1.554 +
1.555 +/**
1.556 +Represents the definition of an index. The key may be unique or primary, it
1.557 +can specify the sort of comparison which is made for Text columns, and it
1.558 +has a list of columns which make up the key. The class is used to construct
1.559 +and interrogate index keys.
1.560 +
1.561 +This class is not intended for user derivation.
1.562 +@publishedAll
1.563 +@released
1.564 +*/
1.565 +class CDbKey : public CBase
1.566 + {
1.567 +public:
1.568 + enum {EUnique=0x01,EPrimary=0x02};
1.569 +public:
1.570 + IMPORT_C CDbKey();
1.571 + IMPORT_C static CDbKey* NewL();
1.572 + IMPORT_C static CDbKey* NewLC();
1.573 + IMPORT_C ~CDbKey();
1.574 + IMPORT_C CDbKey& AddL(const TDbKeyCol& aKeyCol);
1.575 + IMPORT_C void Remove(const TDesC& aColName);
1.576 + IMPORT_C void Clear();
1.577 + inline TInt Count() const;
1.578 + inline const TDbKeyCol& operator[](TInt aCol) const;
1.579 + inline void MakeUnique();
1.580 + inline TBool IsUnique() const;
1.581 + inline void SetComparison(TDbTextComparison aComparison);
1.582 + inline TDbTextComparison Comparison() const;
1.583 + inline void MakePrimary();
1.584 + inline TBool IsPrimary() const;
1.585 +private:
1.586 + CArrayPakFlat<TDbKeyCol> iKeys;
1.587 + TDbTextComparison iComparison;
1.588 + TInt iAttributes;
1.589 + };
1.590 +
1.591 +/**
1.592 +Saves the current location of a rowset, enabling rapid navigation back to a
1.593 +previously visited row or position in the set.
1.594 +
1.595 +Instances of this class are returned by RDbRowSet::Bookmark(), which can later
1.596 +be passed to RDbRowSet::GotoL() to return to the row which was current at
1.597 +the call to Bookmark().
1.598 +
1.599 +@see RDbRowSet::Bookmark()
1.600 +@see RDbRowSet::GotoL()
1.601 +@publishedAll
1.602 +@released
1.603 +*/
1.604 +class TDbBookmark
1.605 + {
1.606 + friend class RDbRowSet;
1.607 +public:
1.608 + struct TMark
1.609 + /** Stores a database bookmark. */
1.610 + {
1.611 + enum {ESize=8};
1.612 + TUint32 iMark[ESize];
1.613 + };
1.614 +private:
1.615 + TMark iMark;
1.616 + };
1.617 +
1.618 +/**
1.619 +A wrapper for an SQL string combined with a text comparison mode.
1.620 +
1.621 +An instance of the class is used as a parameter to RDbView::Prepare(),
1.622 +RDbRowSet::FindL() and RDbRowConstraint::Open().
1.623 +
1.624 +The evaluation of SQL queries or constraints depends on how Text columns are
1.625 +compared so every SQL string is accompanied by a member of the TDbTextComparison
1.626 +enumeration to indicate how comparison is done.
1.627 +
1.628 +If the SQL string contains a LIKE clause with * (asterisks) wildcard then the
1.629 +characters between them must be no longer than length 255.
1.630 +If only one * exists then the length is taken from the start and to the end of
1.631 +the clause. However, if the clause contains a ? (question mark) wildcard
1.632 +within it then the characters between must be no longer than length 253.
1.633 +
1.634 +@see TDbTextComparison
1.635 +@see RDbView::Prepare()
1.636 +@see RDbRowSet::FindL()
1.637 +@see RDbRowConstraint::Open()
1.638 +@publishedAll
1.639 +@released
1.640 +*/
1.641 +class TDbQuery
1.642 + {
1.643 +public:
1.644 + inline TDbQuery(const TDesC& aQuery,TDbTextComparison aComparison=EDbCompareNormal);
1.645 + inline const TDesC& Query() const;
1.646 + inline TDbTextComparison Comparison() const;
1.647 +private:
1.648 + const TDesC& iQuery;
1.649 + TDbTextComparison iComparison;
1.650 + };
1.651 +
1.652 +/**
1.653 +This class is internal and is not intended for use
1.654 +@publishedAll
1.655 +@released
1.656 +*/
1.657 +class RDbHandleBase
1.658 + {
1.659 +public:
1.660 + inline RDbHandleBase();
1.661 + void Close();
1.662 +protected:
1.663 + inline void Set(CDbObject* aObject);
1.664 + CDbObject& Object() const;
1.665 +protected:
1.666 + CDbObject* iObject;
1.667 + };
1.668 +
1.669 +/**
1.670 +This class is internal and is not intended for use.
1.671 +@publishedAll
1.672 +@released
1.673 +*/
1.674 +template <class T>
1.675 +class RDbHandle : public RDbHandleBase
1.676 + {
1.677 +public:
1.678 + inline T* operator=(T* aT);
1.679 + inline T* operator->() const;
1.680 + inline T& operator*() const;
1.681 + inline T* operator()() const;
1.682 + };
1.683 +
1.684 +/**
1.685 +Represents a pre-compiled SQL search-condition, which can be used to
1.686 +test against the current row in a rowset.
1.687 +
1.688 +The constraint is compiled against a specific rowset, and can only be matched
1.689 +against the same rowset using the RDbRowSet::MatchL() function.
1.690 +
1.691 +@see RDbRowSet
1.692 +@publishedAll
1.693 +@released
1.694 +*/
1.695 +class RDbRowConstraint
1.696 + {
1.697 + friend class RDbRowSet;
1.698 +public:
1.699 + IMPORT_C TInt Open(const RDbRowSet& aView,TDbQuery aCriteria);
1.700 + IMPORT_C void Close();
1.701 +private:
1.702 + RDbHandle<CDbRowConstraint> iConstraint;
1.703 + };
1.704 +
1.705 +/**
1.706 +An abstract base class that provides functionality which is shared between
1.707 +SQL view objects and Table objects. This functionality includes most of the
1.708 +cursor navigation, row retrieval and update behaviour of rowsets.
1.709 +
1.710 +Rowset objects do not provide the data for the rowset on which they operate.
1.711 +It is the responsibility of the derived classes RDbView and RDbTable to specify
1.712 +the data source.
1.713 +
1.714 +This class is not intended for user derivation.
1.715 +@publishedAll
1.716 +@released
1.717 +*/
1.718 +class RDbRowSet
1.719 + {
1.720 + friend class RDbRowConstraint;
1.721 + friend class RDbColReadStream;
1.722 + friend class RDbColWriteStream;
1.723 +public:
1.724 + /** Specifies where the rowset should navigate to in the GotoL() function.
1.725 + Their use is encapsulated by the respective member functions FirstL(),
1.726 + NextL() etc. */
1.727 + enum TPosition
1.728 + {
1.729 + /** Move to the first row in the rowset. */
1.730 + EFirst,
1.731 + /** Move to the next row in the rowset. */
1.732 + ENext,
1.733 + /** Move to the previous row in the rowset. */
1.734 + EPrevious,
1.735 + /** Move to the last row in the rowset. */
1.736 + ELast,
1.737 + /** Move to the position before the first row in the rowset. */
1.738 + EBeginning,
1.739 + /** Move to the position after the last row in the rowset. */
1.740 + EEnd
1.741 + };
1.742 +
1.743 + /** Specifies which operations can be performed on a rowset. */
1.744 + enum TAccess
1.745 + {
1.746 + /** All operations can be performed on the rowset. */
1.747 + EUpdatable,
1.748 + /** Row navigation and reading are permitted. */
1.749 + EReadOnly,
1.750 + /** Inserting new rows is the only valid operation on the rowset. */
1.751 + EInsertOnly
1.752 + };
1.753 +
1.754 + /** Specifies the direction to search through the rowset when using the
1.755 + FindL() function. */
1.756 + enum TDirection
1.757 + {
1.758 + /** Search from the current row forwards through the set. */
1.759 + EForwards,
1.760 + /** Search from the current row backwards through the set. */
1.761 + EBackwards
1.762 + };
1.763 +
1.764 + /** Specifies whether the CountL() function should ensure that it returns
1.765 + the exact value which may be a non-trivial task. */
1.766 + enum TAccuracy
1.767 + {
1.768 + /** Take the time, if necessary, to return the exact value. */
1.769 + EEnsure,
1.770 + /** Return any immediately available value. */
1.771 + EQuick
1.772 + };
1.773 +public:
1.774 + IMPORT_C void Close();
1.775 + IMPORT_C void Reset();
1.776 +//
1.777 + IMPORT_C CDbColSet* ColSetL() const;
1.778 + IMPORT_C TInt ColCount() const;
1.779 + IMPORT_C TDbColType ColType(TDbColNo aCol) const;
1.780 + IMPORT_C TDbCol ColDef(TDbColNo aCol) const;
1.781 +//
1.782 + IMPORT_C TBool AtRow() const;
1.783 + IMPORT_C TBool AtBeginning() const;
1.784 + IMPORT_C TBool AtEnd() const;
1.785 +//
1.786 + IMPORT_C TInt CountL(TAccuracy anAccuracy=EEnsure) const;
1.787 + IMPORT_C TBool IsEmptyL() const;
1.788 +//
1.789 + IMPORT_C TBool GotoL(TPosition aPosition);
1.790 + inline void BeginningL();
1.791 + inline void EndL();
1.792 + inline TBool FirstL();
1.793 + inline TBool LastL();
1.794 + inline TBool NextL();
1.795 + inline TBool PreviousL();
1.796 +//
1.797 + IMPORT_C TDbBookmark Bookmark() const;
1.798 + IMPORT_C void GotoL(const TDbBookmark& aMark);
1.799 +//
1.800 + IMPORT_C TBool MatchL(const RDbRowConstraint& aConstraint);
1.801 + IMPORT_C TInt FindL(TDirection aDirection,TDbQuery aCriteria);
1.802 +//
1.803 + IMPORT_C void GetL();
1.804 + IMPORT_C void InsertL();
1.805 + IMPORT_C void InsertCopyL();
1.806 + IMPORT_C void UpdateL();
1.807 + IMPORT_C void PutL();
1.808 + IMPORT_C void Cancel();
1.809 + IMPORT_C void DeleteL();
1.810 +//
1.811 + inline TBool IsColNull(TDbColNo aCol) const;
1.812 + IMPORT_C TInt ColSize(TDbColNo aCol) const;
1.813 + IMPORT_C TInt ColLength(TDbColNo aCol) const;
1.814 +//
1.815 + IMPORT_C TInt8 ColInt8(TDbColNo aCol) const;
1.816 + IMPORT_C TInt16 ColInt16(TDbColNo aCol) const;
1.817 + IMPORT_C TInt32 ColInt32(TDbColNo aCol) const;
1.818 + IMPORT_C TInt64 ColInt64(TDbColNo aCol) const;
1.819 + inline TInt ColInt(TDbColNo aCol) const;
1.820 + IMPORT_C TUint8 ColUint8(TDbColNo aCol) const;
1.821 + IMPORT_C TUint16 ColUint16(TDbColNo aCol) const;
1.822 + IMPORT_C TUint32 ColUint32(TDbColNo aCol) const;
1.823 + inline TUint ColUint(TDbColNo aCol) const;
1.824 + IMPORT_C TReal32 ColReal32(TDbColNo aCol) const __SOFTFP;
1.825 + IMPORT_C TReal64 ColReal64(TDbColNo aCol) const __SOFTFP;
1.826 + inline TReal ColReal(TDbColNo aCol) const;
1.827 + IMPORT_C TTime ColTime(TDbColNo aCol) const;
1.828 + IMPORT_C TPtrC8 ColDes8(TDbColNo aCol) const;
1.829 + IMPORT_C TPtrC16 ColDes16(TDbColNo aCol) const;
1.830 + IMPORT_C TPtrC ColDes(TDbColNo aCol) const;
1.831 +//
1.832 + IMPORT_C void SetColNullL(TDbColNo aCol);
1.833 + inline void SetColL(TDbColNo aCol,TInt aValue);
1.834 + IMPORT_C void SetColL(TDbColNo aCol,TInt32 aValue);
1.835 + IMPORT_C void SetColL(TDbColNo aCol,TInt64 aValue);
1.836 + inline void SetColL(TDbColNo aCol,TUint aValue);
1.837 + IMPORT_C void SetColL(TDbColNo aCol,TUint32 aValue);
1.838 + IMPORT_C void SetColL(TDbColNo aCol,TReal32 aValue) __SOFTFP;
1.839 + IMPORT_C void SetColL(TDbColNo aCol,TReal64 aValue) __SOFTFP;
1.840 + IMPORT_C void SetColL(TDbColNo aCol,TTime aValue);
1.841 + IMPORT_C void SetColL(TDbColNo aCol,const TDesC8& aValue);
1.842 + IMPORT_C void SetColL(TDbColNo aCol,const TDesC16& aValue);
1.843 +private:
1.844 + inline MStreamBuf* ColSourceL(TDbColNo aCol) const;
1.845 + inline MStreamBuf* ColSinkL(TDbColNo aCol);
1.846 + CDbCursor& CheckCol(TDbColNo aCol) const;
1.847 + TDbColumnC ColumnC(TDbColNo aCol,TDbColType aType) const;
1.848 + TDbColumn Column(TDbColNo aCol,TDbColType aType);
1.849 +protected:
1.850 + RDbHandle<CDbCursor> iCursor;
1.851 + };
1.852 +
1.853 +/**
1.854 +Allows any column value to be read as stream data.
1.855 +
1.856 +Note that this is the only way to extract the contents of a Long column from
1.857 +a rowset.
1.858 +
1.859 +Only one column in a rowset object can be opened for reading as a stream at
1.860 +a time, and while it is open no column in the same rowset object may be set
1.861 +using RDbColWriteStream.
1.862 +
1.863 +Null columns result in a read stream with no data. Small numeric columns are
1.864 +maintained in memory as 32-bit values; hence reading a Uint8 column as a stream
1.865 +results in 4 bytes of stream data, not 1.
1.866 +@publishedAll
1.867 +@released
1.868 +*/
1.869 +class RDbColReadStream : public RReadStream
1.870 + {
1.871 +public:
1.872 + IMPORT_C void OpenL(const RDbRowSet& aView,TDbColNo aCol);
1.873 + IMPORT_C void OpenLC(const RDbRowSet& aView,TDbColNo aCol);
1.874 + };
1.875 +
1.876 +/**
1.877 +Writes Long columns when inserting or updating rows in a rowset.
1.878 +
1.879 +Only one column in a rowset object can be opened for writing as a stream at
1.880 +a time.
1.881 +@publishedAll
1.882 +@released
1.883 +*/
1.884 +class RDbColWriteStream : public RWriteStream
1.885 + {
1.886 +public:
1.887 + /** Constructs this object by invoking the default constructor for
1.888 + RWriteStream. */
1.889 + inline RDbColWriteStream() {}
1.890 + inline RDbColWriteStream(const MExternalizer<TStreamRef> &anExternalizer);
1.891 + IMPORT_C void OpenL(RDbRowSet& aView,TDbColNo aCol);
1.892 + IMPORT_C void OpenLC(RDbRowSet& aView,TDbColNo aCol);
1.893 + };
1.894 +
1.895 +/**
1.896 +Describes the desired shape of a view's pre-evaluation window.
1.897 +
1.898 +An instance of this class is passed to the RDbView object as part of the
1.899 +Prepare() function. The different constructors for TDbWindow can specify a view:
1.900 +
1.901 +without pre-evaluation
1.902 +
1.903 +with full pre-evaluation
1.904 +
1.905 +with limited pre-evaluation.
1.906 +
1.907 +@see RDbView
1.908 +@publishedAll
1.909 +@released
1.910 +*/
1.911 +class TDbWindow
1.912 + {
1.913 +public:
1.914 + /** Denotes a full pre-evaluation window. */
1.915 + enum TUnlimited
1.916 + {
1.917 + /** No limit on how many rows may be in the window. */
1.918 + EUnlimited=KMaxTInt
1.919 + };
1.920 + enum {ENone=0};
1.921 +public:
1.922 + inline TDbWindow();
1.923 + inline TDbWindow(TUnlimited);
1.924 + IMPORT_C TDbWindow(TInt aForeSlots,TInt aRearSlots);
1.925 + inline TInt Size() const;
1.926 + inline TInt PreferredPos() const;
1.927 +private:
1.928 + TInt iSize;
1.929 + TInt iPreferredPos;
1.930 + };
1.931 +#if defined(__NO_CLASS_CONSTS__)
1.932 +/**
1.933 +@internalComponent
1.934 +*/
1.935 +#define KDbUnlimitedWindow TDbWindow(TDbWindow::EUnlimited)
1.936 +#else
1.937 +/**
1.938 +@publishedAll
1.939 +@released
1.940 +*/
1.941 +const TDbWindow KDbUnlimitedWindow=TDbWindow(TDbWindow::EUnlimited);
1.942 +#endif
1.943 +
1.944 +/**
1.945 +Generates rowsets from an SQL query. The query is prepared and evaluated
1.946 +using the interface to this class, while the rowset is manipulated using the
1.947 +RDbRowset base class.
1.948 +
1.949 +There are no special rules to consider when deriving from this class.
1.950 +@publishedAll
1.951 +@released
1.952 +*/
1.953 +class RDbView : public RDbRowSet
1.954 + {
1.955 +public:
1.956 + IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,TAccess anAccess=EUpdatable);
1.957 + IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow);
1.958 + IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow,TAccess anAccess);
1.959 + IMPORT_C TInt EvaluateAll();
1.960 + IMPORT_C TInt Evaluate();
1.961 + IMPORT_C void Evaluate(TRequestStatus& aStatus);
1.962 + IMPORT_C TBool Unevaluated() const;
1.963 + };
1.964 +
1.965 +/**
1.966 +This class is internal and is not intended for use.
1.967 +@publishedAll
1.968 +@released
1.969 +*/
1.970 +template <class T>
1.971 +class TUnion
1.972 + {
1.973 +public:
1.974 + inline operator const T&() const;
1.975 + inline const T& operator()() const;
1.976 + inline T& operator()();
1.977 + inline void Set(const T& aT);
1.978 +private:
1.979 + TUint8 iRep[sizeof(T)];
1.980 + };
1.981 +
1.982 +/**
1.983 +This class is internal and is not intended for use.
1.984 +@publishedAll
1.985 +@released
1.986 +*/
1.987 +class TDbLookupKey
1.988 + {
1.989 +public:
1.990 + struct SColumn
1.991 + {
1.992 + union
1.993 + {
1.994 + TInt32 iInt32;
1.995 + TUint32 iUint32;
1.996 + TUnion<TInt64> iInt64;
1.997 + TReal32 iReal32;
1.998 + TReal64 iReal64;
1.999 + TUnion<TTime> iTime;
1.1000 + struct {const TText8* iPtr;TInt iLength;} iDes8;
1.1001 + struct {const TText16* iPtr;TInt iLength;} iDes16;
1.1002 + };
1.1003 + TDbColType iType;
1.1004 + };
1.1005 +public:
1.1006 + inline TDbLookupKey();
1.1007 + inline TInt Count() const;
1.1008 + inline const SColumn* First() const;
1.1009 + void Add(TInt aKey);
1.1010 + void Add(TUint aKey);
1.1011 + void Add(TInt64 aKey);
1.1012 + void Add(TReal32 aKey) __SOFTFP;
1.1013 + void Add(TReal64 aKey) __SOFTFP;
1.1014 + void Add(TTime aKey);
1.1015 + void Add(const TDesC8& aKey);
1.1016 + void Add(const TDesC16& aKey);
1.1017 +private:
1.1018 + SColumn& NextKey();
1.1019 +private:
1.1020 + TInt iCount;
1.1021 + SColumn iKey[1]; // at least one
1.1022 + };
1.1023 +
1.1024 +/**
1.1025 +Database key value.
1.1026 +
1.1027 +The class encapsulates a key value which is passed to RDbTable::SeekL(), for
1.1028 +lookup in the currently active index on that rowset.
1.1029 +
1.1030 +An instance of this class can store a key value of any type.
1.1031 +
1.1032 +Note that the class can only hold a single-column key. Use TDbSeekMultiKey
1.1033 +for multi-column keys.
1.1034 +
1.1035 +@see TDbSeekMultiKey
1.1036 +@see RDbTable
1.1037 +@publishedAll
1.1038 +@released
1.1039 +*/
1.1040 +class TDbSeekKey
1.1041 + {
1.1042 + friend class RDbTable;
1.1043 +public:
1.1044 + inline TDbSeekKey();
1.1045 + inline TDbSeekKey(TInt aKey);
1.1046 + inline TDbSeekKey(TUint aKey);
1.1047 + inline TDbSeekKey(TInt64 aKey);
1.1048 + inline TDbSeekKey(TReal32 aKey);
1.1049 + inline TDbSeekKey(TReal64 aKey);
1.1050 + inline TDbSeekKey(TTime aKey);
1.1051 + inline TDbSeekKey(const TDesC8& aKey);
1.1052 + inline TDbSeekKey(const TDesC16& aKey);
1.1053 + IMPORT_C TDbSeekKey& Add(TInt aKey);
1.1054 + IMPORT_C TDbSeekKey& Add(TUint aKey);
1.1055 + IMPORT_C TDbSeekKey& Add(TInt64 aKey);
1.1056 + IMPORT_C TDbSeekKey& Add(TReal32 aKey) __SOFTFP;
1.1057 + IMPORT_C TDbSeekKey& Add(TReal64 aKey) __SOFTFP;
1.1058 + IMPORT_C TDbSeekKey& Add(TTime aKey);
1.1059 + IMPORT_C TDbSeekKey& Add(const TDesC8& aKey);
1.1060 + IMPORT_C TDbSeekKey& Add(const TDesC16& aKey);
1.1061 +private:
1.1062 + TDbLookupKey& Check();
1.1063 +protected:
1.1064 + inline TDbSeekKey(TInt aKeys,TInt);
1.1065 +private:
1.1066 + TInt iMaxKeys;
1.1067 + TDbLookupKey iKey;
1.1068 + };
1.1069 +
1.1070 +/**
1.1071 +Database multi-column key value.
1.1072 +
1.1073 +The class extends the behaviour of TDbSeekKey by allowing multi-column indexes
1.1074 +to be searched using multi-column key values.
1.1075 +
1.1076 +The template parameter S specifies the maximum number of column values that
1.1077 +can be added to the key value.
1.1078 +
1.1079 +Use the TDbSeekKey::Add() members to append the values for each column in
1.1080 +the key value.
1.1081 +@publishedAll
1.1082 +@released
1.1083 +*/
1.1084 +template<TInt S>
1.1085 +class TDbSeekMultiKey : public TDbSeekKey
1.1086 + {
1.1087 +public:
1.1088 + inline TDbSeekMultiKey();
1.1089 +private:
1.1090 + TDbLookupKey::SColumn iExtraKeys[S-1];
1.1091 + };
1.1092 +
1.1093 +/**
1.1094 +Provides access to table data as a rowset, allowing manipulation of a named
1.1095 +table in the database. Additionally, a named index can be used to order the
1.1096 +rowset, and to provide fast key-based row retrieval from the table.
1.1097 +
1.1098 +There are no special rules to consider when deriving from this class.
1.1099 +@publishedAll
1.1100 +@released
1.1101 +*/
1.1102 +class RDbTable : public RDbRowSet
1.1103 + {
1.1104 +public:
1.1105 + /** Database table seek comparison types. */
1.1106 + enum TComparison
1.1107 + {
1.1108 + /** Retrieve the last row which is strictly less than the key value. */
1.1109 + ELessThan,
1.1110 + /** Retrieve the last row which is equal to or less than the key
1.1111 + value. */
1.1112 + ELessEqual,
1.1113 + /** Retrieve the first row which is equal to the key value. */
1.1114 + EEqualTo,
1.1115 + /** Retrieve the first row which is equal to or greater than the key
1.1116 + value. */
1.1117 + EGreaterEqual,
1.1118 + /** Retrieve the first row which is strictly greater than the key
1.1119 + value. */
1.1120 + EGreaterThan
1.1121 + };
1.1122 +public:
1.1123 + IMPORT_C TInt Open(RDbDatabase& aDatabase,const TDesC& aName,TAccess anAccess=EUpdatable);
1.1124 + inline TInt SetIndex(const TDesC& anIndex);
1.1125 + inline TInt SetNoIndex();
1.1126 + IMPORT_C TBool SeekL(const TDbSeekKey& aKey,TComparison aComparison=EEqualTo);
1.1127 +private:
1.1128 + IMPORT_C TInt SetIndex(const TDesC* anIndex);
1.1129 + };
1.1130 +
1.1131 +/**
1.1132 +@publishedAll
1.1133 +@released
1.1134 +*/
1.1135 +class CDbNames : public CBase
1.1136 + {
1.1137 +private:
1.1138 + inline CDbNames();
1.1139 +public:
1.1140 + static CDbNames* NewLC();
1.1141 + ~CDbNames();
1.1142 + inline TInt Count() const;
1.1143 + inline const TDesC& operator[](TInt anIndex) const;
1.1144 + IMPORT_C void AddL(const TDesC& aName);
1.1145 +private:
1.1146 + CArrayPakFlat<TDbNameC> iList;
1.1147 + };
1.1148 +/**
1.1149 +@publishedAll
1.1150 +@released
1.1151 +*/
1.1152 +typedef CDbNames CDbTableNames,CDbIndexNames,CDbDatabaseNames;
1.1153 +
1.1154 +/**
1.1155 +The maximum length for a generic DBMS string, which might be transferred from DBMS server
1.1156 +to the DBMS client using IPC.
1.1157 +@publishedAll
1.1158 +@released
1.1159 +*/
1.1160 +const TInt KDbMaxStrLen = 256;
1.1161 +
1.1162 +/**
1.1163 +Represents a generic read-only DBMS string. It maps to a non-modifiable buffer descriptor
1.1164 +with maximum size KDbMaxStrLen.
1.1165 +
1.1166 +@see TBufC
1.1167 +@publishedAll
1.1168 +@released
1.1169 +*/
1.1170 +typedef TBufC<KDbMaxStrLen> TDbStringC;
1.1171 +
1.1172 +/**
1.1173 +CDbStrings encapsulates functionality used for transferring an array of strings from
1.1174 +DBMS server to the DBMS client. The maximal length of each element of the array is
1.1175 +KDbMaxStrLen characters.
1.1176 +The typical usage pattern of CDbStrings class is:
1.1177 +@code
1.1178 +CDbStrings* strings = <a call of an exported DBMS method>;
1.1179 +TInt cnt = strings.Count();
1.1180 +for(TInt i=0;i<cnt;++i)
1.1181 + {
1.1182 + const TDesC& str = (*strings)[i];
1.1183 + <do something with "str" variable>;
1.1184 + }
1.1185 +delete strings;
1.1186 +@endcode
1.1187 +@publishedAll
1.1188 +@released
1.1189 +*/
1.1190 +class CDbStrings : public CBase
1.1191 + {
1.1192 +private:
1.1193 + inline CDbStrings();
1.1194 +public:
1.1195 + static CDbStrings* NewLC();
1.1196 + virtual ~CDbStrings();
1.1197 + inline TInt Count() const;
1.1198 + inline const TDesC& operator[](TInt aIndex) const;
1.1199 + void AddL(const TDesC& aStr);
1.1200 +private:
1.1201 + CArrayPakFlat<TDbStringC> iList;
1.1202 + };
1.1203 +
1.1204 +/**
1.1205 +Abstract class providing the functionality of a database.
1.1206 +
1.1207 +The source of the database and the implementation characteristics of a particular
1.1208 +database are provided by a class derived from RDbDatabase.
1.1209 +
1.1210 +DBMS has one such implementation: the store database.
1.1211 +
1.1212 +This class is not intended for user derivation.
1.1213 +
1.1214 +Note: For functions (i.e. Execute) that take an Sql string, if the string
1.1215 +contains a LIKE clause with * (asterisks) wildcard then the
1.1216 +characters between them must be no longer than length 255.
1.1217 +If only one * exists then the length is taken from the start and to the end of
1.1218 +the clause. However, if the clause contains a ? (question mark) wildcard
1.1219 +within it then the characters between must be no longer than length 253.
1.1220 +
1.1221 +@publishedAll
1.1222 +@released
1.1223 +*/
1.1224 +class RDbDatabase
1.1225 + {
1.1226 + friend class RDbView;
1.1227 + friend class RDbTable;
1.1228 + friend class RDbIncremental;
1.1229 + friend class RDbUpdate;
1.1230 + friend class RDbNotifier;
1.1231 +public:
1.1232 + struct TSize {TInt iSize;TInt iUsage;};
1.1233 +public:
1.1234 + IMPORT_C void Close();
1.1235 + IMPORT_C TInt Destroy();
1.1236 +//
1.1237 + IMPORT_C TBool IsDamaged() const;
1.1238 + IMPORT_C TInt Recover();
1.1239 +//
1.1240 + IMPORT_C TInt UpdateStats();
1.1241 + IMPORT_C TSize Size() const;
1.1242 + IMPORT_C TInt Compact();
1.1243 + IMPORT_C TInt Begin();
1.1244 + IMPORT_C TInt Commit();
1.1245 + IMPORT_C void Rollback();
1.1246 + IMPORT_C TBool InTransaction() const;
1.1247 +//
1.1248 + inline TInt CreateTable(const TDesC& aName,const CDbColSet& aDef);
1.1249 + inline TInt CreateTable(const TDesC& aName,const CDbColSet& aDef,const CDbKey& aPrimaryKey);
1.1250 + IMPORT_C TInt DropTable(const TDesC& aName);
1.1251 + IMPORT_C TInt AlterTable(const TDesC& aName,const CDbColSet& aNewDef);
1.1252 + IMPORT_C TInt CreateIndex(const TDesC& aName,const TDesC& aTable,const CDbKey& aKey);
1.1253 + IMPORT_C TInt DropIndex(const TDesC& aName,const TDesC& aTable);
1.1254 +//
1.1255 + IMPORT_C TInt Execute(const TDesC& aSql,TDbTextComparison aComparison=EDbCompareNormal);
1.1256 +//
1.1257 + IMPORT_C CDbTableNames* TableNamesL() const;
1.1258 + IMPORT_C CDbColSet* ColSetL(const TDesC& aName) const;
1.1259 + IMPORT_C CDbIndexNames* IndexNamesL(const TDesC& aTable) const;
1.1260 + IMPORT_C CDbKey* KeyL(const TDesC& aName,const TDesC& aTable) const;
1.1261 +private:
1.1262 + IMPORT_C TInt CreateTable(const TDesC& aName,const CDbColSet& aColSet,const CDbKey* aPrimaryKey);
1.1263 +protected:
1.1264 + RDbHandle<CDbDatabase> iDatabase;
1.1265 + };
1.1266 +
1.1267 +/**
1.1268 +Provides the interface for performing long-running database operations in
1.1269 +incremental steps, allowing application programs to remain responsive to other
1.1270 +events.
1.1271 +
1.1272 +After an operation has begun, a standard interface is used to continue and
1.1273 +complete all incremental operations. On successful return from one of the
1.1274 +initiating functions, a step value is also returned. This gives the progress
1.1275 +indication and is, initially, positive. This value should be passed into
1.1276 +subsequent steps in the operation, each of which may decrement the value by
1.1277 +some amount, although they are allowed to leave it unchanged. The value
1.1278 +reaches zero, if, and only if the operation completes.
1.1279 +
1.1280 +While an incremental operation is in progress, the database cannot be used
1.1281 +for any other operations such as opening tables or preparing views.
1.1282 +
1.1283 +Starting an incremental operation also requires that no rowsets are open on
1.1284 +the database and that no commit is pending for data manipulation transactions.
1.1285 +
1.1286 +If no explicit transaction has been started by the database, then an automatic
1.1287 +transaction is begun when any incremental operation is started and is committed
1.1288 +when complete or rolled back if the operation either fails or is abandoned
1.1289 +prior to completion.
1.1290 +@publishedAll
1.1291 +@released
1.1292 +*/
1.1293 +class RDbIncremental
1.1294 + {
1.1295 +public:
1.1296 + IMPORT_C void Close();
1.1297 + IMPORT_C TInt Next(TInt& aStep);
1.1298 + IMPORT_C void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);
1.1299 +//
1.1300 + IMPORT_C TInt Recover(RDbDatabase& aDatabase,TInt& aStep);
1.1301 + IMPORT_C TInt Compact(RDbDatabase& aDatabase,TInt& aStep);
1.1302 + IMPORT_C TInt DropTable(RDbDatabase& aDatabase,const TDesC& aTable,TInt& aStep);
1.1303 + IMPORT_C TInt AlterTable(RDbDatabase& aDatabase,const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep);
1.1304 + IMPORT_C TInt CreateIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,const CDbKey& aKey,TInt& aStep);
1.1305 + IMPORT_C TInt DropIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,TInt& aStep);
1.1306 + inline TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TInt& aStep);
1.1307 + IMPORT_C TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep);
1.1308 + IMPORT_C TInt UpdateStats(RDbDatabase& aDatabase,TInt& aStep);
1.1309 +private:
1.1310 + RDbHandle<CDbIncremental> iState;
1.1311 + };
1.1312 +
1.1313 +/**
1.1314 +Provides an interface to allow incremental execution of a DML (SQL data
1.1315 +update) statement.
1.1316 +
1.1317 +This class offers similar behaviour to the RDbIncremental class, in that it
1.1318 +allows an application to perform long running operations while remaining
1.1319 +responsive to events. However, unlike that class, RDbUpdate is restricted to
1.1320 +executing DML statements.
1.1321 +
1.1322 +@see RDbIncremental
1.1323 +@publishedAll
1.1324 +@released
1.1325 +*/
1.1326 +class RDbUpdate
1.1327 + {
1.1328 +public:
1.1329 + IMPORT_C TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison=EDbCompareNormal);
1.1330 + IMPORT_C void Close();
1.1331 +//
1.1332 + IMPORT_C TInt Next();
1.1333 + IMPORT_C void Next(TRequestStatus& aStatus);
1.1334 + IMPORT_C TInt RowCount() const;
1.1335 +private:
1.1336 + RDbHandle<CDbIncremental> iUpdate;
1.1337 + TPckgBuf<TInt> iRows;
1.1338 + };
1.1339 +
1.1340 +/**
1.1341 +Provides notification of database changes to clients.
1.1342 +
1.1343 +This is useful for shared databases.
1.1344 +@publishedAll
1.1345 +@released
1.1346 +*/
1.1347 +class RDbNotifier
1.1348 + {
1.1349 +public:
1.1350 + /** Defines the events which may be reported by a DBMS change notifier
1.1351 + through this RDbNotifier object.
1.1352 +
1.1353 + Each enumerator corresponds to a distinct event type.
1.1354 +
1.1355 + The changes are reported through a TRequestStatus object when an
1.1356 + outstanding notification request completes.
1.1357 +
1.1358 + Notes
1.1359 +
1.1360 + If further database events occur while a client is handling the completion
1.1361 + of a previous event, the notifier remembers the most significant event. The
1.1362 + order of importance is:
1.1363 +
1.1364 + ERecover > ERollback > ECommit
1.1365 +
1.1366 + where the symbol > means "is more important than" */
1.1367 + enum TEvent
1.1368 + {
1.1369 + /** The database has been closed. */
1.1370 + EClose,
1.1371 + /** All read locks have been removed. */
1.1372 + EUnlock,
1.1373 + /** A transaction has been committed. */
1.1374 + ECommit,
1.1375 + /** A transaction has been rolled back */
1.1376 + ERollback,
1.1377 + /** The database has been recovered */
1.1378 + ERecover
1.1379 + };
1.1380 +public:
1.1381 + IMPORT_C TInt Open(RDbDatabase& aDatabase);
1.1382 + IMPORT_C void Close();
1.1383 +//
1.1384 + IMPORT_C void NotifyUnlock(TRequestStatus& aStatus);
1.1385 + IMPORT_C void NotifyChange(TRequestStatus& aStatus);
1.1386 + IMPORT_C void Cancel();
1.1387 +private:
1.1388 + RDbHandle<CDbNotifier> iNotifier;
1.1389 + };
1.1390 +
1.1391 +/**
1.1392 +Client-server databases
1.1393 +
1.1394 +Represents a session with the DBMS server. A thread uses this class to set
1.1395 +up a DBMS server session and this provides the basis for sharing databases
1.1396 +with other threads.
1.1397 +@publishedAll
1.1398 +@released
1.1399 +*/
1.1400 +class RDbs : public RSessionBase
1.1401 + {
1.1402 +public:
1.1403 + /**
1.1404 + This enum is used in GetDatabasePolicy/GetTablePolicy/GetTablePolicies calls and specifies
1.1405 + requested security policy type: read/write/schema.
1.1406 + @publishedAll
1.1407 + @released
1.1408 + */
1.1409 + typedef enum {EReadPolicy, EWritePolicy, ESchemaPolicy} TPolicyType;
1.1410 +
1.1411 +public:
1.1412 + IMPORT_C static TVersion Version();
1.1413 + IMPORT_C TInt Connect();
1.1414 + IMPORT_C CDbDatabaseNames* DatabaseNamesL(TDriveNumber aDrive, TUid aPolicyUid);
1.1415 + IMPORT_C TInt CopyDatabase(const TDesC& aSrcDbName, const TDesC& aDestDbName, TUid aPolicyUid);
1.1416 + IMPORT_C TInt DeleteDatabase(const TDesC& aDbName, TUid aPolicyUid);
1.1417 + IMPORT_C TInt GetDatabasePolicy(TUid aPolicyUid, TPolicyType aPolicyType,
1.1418 + TSecurityPolicy& aDbPolicy);
1.1419 + IMPORT_C TInt GetTablePolicy(TUid aPolicyUid, const TDesC& aTableName,
1.1420 + TPolicyType aPolicyType, TSecurityPolicy& aTablePolicy);
1.1421 + IMPORT_C TInt GetTablePolicies(TUid aPolicyUid, const TDesC& aTableName,
1.1422 + TPolicyType aPolicyType,
1.1423 + TSecurityPolicy& aDbPolicy, TSecurityPolicy& aTablePolicy);
1.1424 + //
1.1425 + IMPORT_C void ResourceMark();
1.1426 + IMPORT_C void ResourceCheck();
1.1427 + IMPORT_C TInt ResourceCount();
1.1428 + IMPORT_C void SetHeapFailure(TInt aTAllocFail,TInt aRate);
1.1429 +
1.1430 + IMPORT_C TInt ReserveDriveSpace(TInt aDriveNo, TInt aSpace);
1.1431 + IMPORT_C void FreeReservedSpace(TInt aDriveNo);
1.1432 + IMPORT_C TInt GetReserveAccess(TInt aDriveNo);
1.1433 + IMPORT_C TInt ReleaseReserveAccess(TInt aDriveNo);
1.1434 +
1.1435 + IMPORT_C TInt GetBackupPath(TSecureId aRequesterSid, const TDesC& aDbName,
1.1436 + TUid aDbPolicyUid, TDes& aBackupPath);
1.1437 + IMPORT_C CDbStrings* BackupPathsL(TSecureId aRequesterSid, TUid aDbPolicyUid);
1.1438 +
1.1439 +private:
1.1440 + TInt DoConnect();
1.1441 + TInt SessionMessage(TInt aFunction);
1.1442 + TInt GetPolicy(TUid aPolicyUid, const TDesC& aTableName,
1.1443 + TUint aMask, TSecurityPolicy& aPolicy);
1.1444 + };
1.1445 +
1.1446 +/**
1.1447 +Generic database implementation
1.1448 +@publishedAll
1.1449 +@released
1.1450 +*/
1.1451 +class RDbNamedDatabase : public RDbDatabase
1.1452 + {
1.1453 +public:
1.1454 + /** Specifies which operations can be performed on a rowset. */
1.1455 + enum TAccess
1.1456 + {
1.1457 + EReadWrite,
1.1458 + /** Row navigation and reading are permitted. */
1.1459 + EReadOnly
1.1460 + };
1.1461 +public:
1.1462 + IMPORT_C TInt Create(RDbs& aDbs, const TDesC& aDatabase, const TDesC& aFormat);
1.1463 + IMPORT_C TInt Create(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
1.1464 + IMPORT_C TInt Replace(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
1.1465 + IMPORT_C TInt Open(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC(),TAccess aMode=EReadWrite);
1.1466 + IMPORT_C TInt Open(RDbs& aDbs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
1.1467 + };
1.1468 +
1.1469 +/**
1.1470 +@internalComponent
1.1471 +*/
1.1472 +const TInt KDbStoreMaxColumnLength=255;
1.1473 +
1.1474 +/**
1.1475 +DBMS Store database implementation
1.1476 +@publishedAll
1.1477 +@released
1.1478 +*/
1.1479 +class RDbStoreDatabase : public RDbDatabase
1.1480 + {
1.1481 +public:
1.1482 + IMPORT_C TStreamId CreateL(CStreamStore* aStore);
1.1483 + IMPORT_C void OpenL(CStreamStore* aStore,TStreamId anId);
1.1484 + IMPORT_C static void CompressL(CStreamStore& aStore,TStreamId aId);
1.1485 + IMPORT_C static void DecompressL(CStreamStore& aStore,TStreamId aId);
1.1486 + };
1.1487 +
1.1488 +#include <d32dbms.inl>
1.1489 +#endif