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