1 d32dbms.h

     1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #if !defined(__D32DBMS_H__)

    17 #define __D32DBMS_H__

    18 

    19 #ifndef __S32STD_H__

    20 #include <s32std.h>

    21 #endif

    22 #ifndef __F32FILE_H__

    23 #include <f32file.h>

    24 #endif

    25 

    26 // other classes referenced

    27 class RFs;

    28 class CDbObject;

    29 class CDbRowConstraint;

    30 class CDbCursor;

    31 class CDbDatabase;

    32 class CDbIncremental;

    33 class CDbNotifier;

    34 class TDbColumn;

    35 class TDbColumnC;

    36 

    37 // classes defined

    38 class TDbCol;

    39 class CDbColSet;

    40 class TDbColSetIter;

    41 class TDbKeyCol;

    42 class CDbKey;

    43 class TDbBookmark;

    44 class TDbQuery;

    45 class RDbHandleBase;

    46 template<class T> class RDbHandle;

    47 class RDbRowConstraint;

    48 class RDbRowSet;

    49 class RDbColReadStream;

    50 class RDbColWriteStream;

    51 class TDbWindow;

    52 class RDbView;

    53 template<class T> class TUnion;

    54 class TDbLookupKey;

    55 class TDbSeekKey;

    56 template<TInt S> class TDbSeekMultiKey;

    57 class RDbTable;

    58 class CDbNames;

    59 class RDbDatabase;

    60 class RDbIncremental;

    61 class RDbUpdate;

    62 class RDbNotifier;

    63 class RDbs;

    64 class RDbNamedDatabase;

    65 class RDbStoreDatabase;

    66 

    67 /**

    68 The maximum length for a DBMS name: 64 characters.

    69 @publishedAll

    70 @released

    71 */

    72 const TInt KDbMaxName=0x40;

    73 

    74 /**

    75 The maximum length for a DBMS column name: 64 characters.

    76 @publishedAll

    77 @released

    78 */

    79 const TInt KDbMaxColName=KDbMaxName;

    80 

    81 /** 

    82 Represents a writable DBMS name. It maps to a modifiable buffer descriptor 

    83 with maximum size KDbMaxName.

    84 

    85 Notes:

    86 

    87 A DBMS name must begin with an alphabetic character, after which any alphabetic, 

    88 numeric or the _ (underscore) character may be used. DBMS names are also limited 

    89 to 64 characters in length.

    90 

    91 Table names must be unique within a database, and columns and indexes must 

    92 have unique names within the table to which they belong. For the purposes 

    93 of uniqueness and identification, the names are folded before comparison, 

    94 so two columns named column_one and Column_ONE are considered to have the 

    95 same name.

    96 

    97 @see TBuf 

    98 @publishedAll

    99 @released

   100 */

   101 typedef TBuf<KDbMaxName> TDbName;

   102 

   103 /** Represents a non-writeable DBMS name. It maps to a non modifiable buffer descriptor 

   104 with maximum size KDbMaxName.

   105 

   106 Notes:

   107 

   108 A DBMS name must begin with an alphabetic character, after which any alphabetic, 

   109 numeric or the _ (underscore) character may be used. DBMS names are also limited 

   110 to 64 characters in length.

   111 

   112 Table names must be unique within a database, and columns and indexes must 

   113 have unique names within the table to which they belong. For the purposes 

   114 of uniqueness and identification, the names are folded before comparison, 

   115 so two columns named column_one and Column_ONE are considered to have the 

   116 same name.

   117 

   118 @see TBufC 

   119 @publishedAll

   120 @released

   121 */

   122 typedef TBufC<KDbMaxName> TDbNameC;

   123 

   124 /** Represents a writable DBMS column name. It maps to a modifiable buffer descriptor 

   125 with maximum size KDbMaxColName.

   126 

   127 Notes:

   128 

   129 A DBMS name must begin with an alphabetic character, after which any alphabetic, 

   130 numeric or the _ (underscore) character may be used. DBMS names are also limited 

   131 to 64 characters in length.

   132 

   133 Table names must be unique within a database, and columns and indexes must 

   134 have unique names within the table to which they belong. For the purposes 

   135 of uniqueness and identification, the names are folded before comparison, 

   136 so two columns named column_one and Column_ONE are considered to have the 

   137 same name. 

   138 @publishedAll

   139 @released

   140 */

   141 typedef TBuf<KDbMaxColName> TDbColName;

   142 

   143 /** Represents a non-writable DBMS column name. It maps to a non-modifiable buffer 

   144 descriptor with maximum size KDbMaxColName.

   145 

   146 Notes:

   147 

   148 A DBMS name must begin with an alphabetic character, after which any alphabetic, 

   149 numeric or the _ (underscore) character may be used. DBMS names are also limited 

   150 to 64 characters in length.

   151 

   152 Table names must be unique within a database, and columns and indexes must 

   153 have unique names within the table to which they belong. For the purposes 

   154 of uniqueness and identification, the names are folded before comparison, 

   155 so two columns named column_one and Column_ONE are considered to have the 

   156 same name.

   157 

   158 @see TBufC 

   159 @publishedAll

   160 @released

   161 */

   162 typedef TBufC<KDbMaxColName> TDbColNameC;

   163 

   164 /** Specifies when DBMS objects require a column ordinal to identify a column in 

   165 a column set or in a rowset.

   166 

   167 Note that KDbNullColNo is a special value of TDbColNo used to indicate that 

   168 no such column exists. 

   169 @publishedAll

   170 @released

   171 */

   172 typedef TInt TDbColNo;

   173 

   174 /** 

   175 Indicates that a specified column does not exist. 

   176 @publishedAll

   177 @released

   178 */

   179 const TDbColNo KDbNullColNo=0;

   180 

   181 /** 

   182 A value returned by RDbRowSet::Count() when the number of rows cannot be determined.

   183 

   184 @see RDbRowSet 

   185 @publishedAll

   186 @released

   187 */

   188 const TInt KDbUndefinedCount=-1;

   189 

   190 /** 

   191 The length of a column is undefined. 

   192 @publishedAll

   193 @released

   194 */

   195 const TInt KDbUndefinedLength=-1;

   196 

   197 /** 

   198 The default text column length. This is equal to 50. 

   199 @publishedAll

   200 @released

   201 */

   202 const TInt KDbDefaultTextColLength=50;

   203 

   204 /** 

   205 Represents every supported column type. 

   206 @publishedAll

   207 @released

   208 */

   209 enum TDbColType

   210 	{

   211 	/** The column stores a single bit.

   212 	

   213 	Representation range: 0 to 1

   214 	

   215 	Storage: 1 bit

   216 	

   217 	Auto-increment: Yes

   218 	

   219 	Index key: Yes */

   220 	EDbColBit,

   221 

   222 	/** The column stores an 8-bit signed integer.

   223 	

   224 	Representation range: -2^7 to 2^7 - 1

   225 	

   226 	Storage: 1 byte

   227 	

   228 	Auto-increment: Yes

   229 	

   230 	Index key: Yes */

   231 	EDbColInt8,

   232 

   233 	/** The column stores an 8-bit unsigned integer.

   234 	

   235 	Representation range: 0 to 2^8-1

   236 	

   237 	Storage: 1 byte

   238 	

   239 	Auto-increment: Yes

   240 	

   241 	Index key: Yes */

   242 	EDbColUint8,

   243 

   244 	/** The column stores a 16-bit signed integer.

   245 	

   246 	Representation range: -2^15 to 2^15 - 1

   247 	

   248 	Storage: 2 bytes

   249 	

   250 	Auto-increment: Yes

   251 	

   252 	Index key: Yes */

   253 	EDbColInt16,

   254 

   255 	/** The column stores a 16-bit unsigned integer.

   256 	

   257 	Representation range: 0 to 2^16-1

   258 	

   259 	Storage: 2 bytes

   260 	

   261 	Auto-increment: Yes

   262 	

   263 	Index key: Yes */

   264 	EDbColUint16,

   265 

   266 	/** The column stores a 32-bit signed integer.

   267 	

   268 	Representation range: -2^31 to 2^31 - 1

   269 	

   270 	Storage: 4 bytes

   271 	

   272 	Auto-increment: Yes

   273 	

   274 	Index key: Yes */

   275 	EDbColInt32,

   276 

   277 	/** The column stores a 32-bit unsigned integer.

   278 	

   279 	Representation range: 0 to 2^32-1

   280 	

   281 	Storage: 4 bytes

   282 	

   283 	Auto-increment: Yes

   284 	

   285 	Index key: Yes */

   286 	EDbColUint32,

   287 

   288 	/** The column stores a 64-bit signed integer.

   289 	

   290 	Representation range: -2^63 to 2^63 - 1

   291 	

   292 	Storage: 8 bytes

   293 	

   294 	Auto-increment: No

   295 	

   296 	Index key: Yes */

   297 	EDbColInt64,

   298 

   299 	/** The column stores a 32-bit floating point value.

   300 	

   301 	Representation range: 1.4 X 10^-45 to 3.40282 X 10^38

   302 	

   303 	Storage: 4 bytes

   304 	

   305 	Auto-increment: No

   306 	

   307 	Index key: Yes */

   308 	EDbColReal32,

   309 

   310 	/** The column stores a 64-bit floating point value.

   311 	

   312 	Representation range: 2.2 X 10^-308 to 1.79769 X 10^308

   313 	

   314 	Storage: 8 bytes

   315 	

   316 	Auto-increment: No

   317 	

   318 	Index key: Yes */

   319 	EDbColReal64,

   320 

   321 	/** The column stores a date/time value.

   322 	

   323 	Representation range: 1/1/0 to 31/12/9999

   324 	

   325 	Storage: 8 bytes

   326 	

   327 	Auto-increment: No

   328 	

   329 	Index key: Yes */

   330 	EDbColDateTime,

   331 

   332 	/** The column stores a (short) variable length of non-Unicode text data.

   333 	

   334 	Representation range: 0 to 256 characters

   335 	

   336 	Storage: 0 to 256 bytes

   337 	

   338 	Auto-increment: No

   339 	

   340 	Index key: Yes */

   341 	EDbColText8,

   342 

   343 	/** The column stores a (short) variable length of Unicode text data.

   344 	

   345 	Representation range: 0 to 256 characters

   346 	

   347 	Storage: 0 to 512 bytes

   348 	

   349 	Auto-increment: No

   350 	

   351 	Index key: Yes */

   352 	EDbColText16,

   353 

   354 	/** The column stores a (short) variable length of untyped data.

   355 	

   356 	Representation range: 0 to 255 bytes

   357 	

   358 	Storage: 0 to 256 bytes

   359 	

   360 	Auto-increment: No

   361 	

   362 	Index key: No */

   363 	EDbColBinary,

   364 

   365 	/** The column stores a potentially large amount of non-Unicode text data.

   366 	

   367 	Representation range: 0 to 2^31 characters

   368 	

   369 	Storage: 0 to 2 Gbytes

   370 	

   371 	Auto-increment: No

   372 	

   373 	Index key: Truncated */

   374 	EDbColLongText8,

   375 

   376 	/** The column stores a potentially large amount of Unicode text data.

   377 	

   378 	Representation range: 0 to 2^30 characters

   379 	

   380 	Storage: 0 to 2 Gbytes

   381 	

   382 	Auto-increment: No

   383 	

   384 	Index key: Truncated */

   385 	EDbColLongText16,

   386 

   387 	/** The column stores a potentially large amount of untyped data.

   388 	

   389 	Representation range: 0 to 2^31 bytes

   390 	

   391 	Storage: 0 to 2 Gbytes

   392 	

   393 	Auto-increment: No

   394 	

   395 	Index key: No */

   396 	EDbColLongBinary,

   397 

   398 	/** This is equivalent to EDbColText8 if the build is narrow, and 

   399 	EDbColText16 if the build is Unicode. */

   400 	EDbColText=EDbColText16,

   401 

   402 	/** This is equivalent to EDbColLongText8 if the build is narrow, and 

   403 	EDbColLongText16 if the build is Unicode. */

   404 	EDbColLongText=EDbColLongText16

   405 	};

   406 

   407 /** 

   408 Represents different ways of comparing Text and LongText columns.

   409 

   410 This affects the ordering of indexes (see CDbKey), the evaluation of SQL 

   411 queries and matching row constraints (see TDbQuery). 

   412 @publishedAll

   413 @released

   414 */

   415 enum TDbTextComparison 

   416 	{

   417 	/** Use standard text comparison and ordering. */

   418 	EDbCompareNormal,

   419 	/** Use folded text for comparison and ordering. */

   420 	EDbCompareFolded,

   421 	/** Use collation for comparison and ordering. */

   422 	EDbCompareCollated

   423 	};

   424 

   425 /** 

   426 Defines a column in a table or rowset. 

   427 

   428 The data members are public because this is really a structure to group the 

   429 attributes of the column together. 

   430 

   431 Three non-default constructors are provided for convenience. 

   432 @publishedAll

   433 @released

   434 */

   435 class TDbCol

   436 	{

   437 	friend class CDbColSet;

   438 public:

   439 	enum {ENotNull=0x01,EAutoIncrement=0x02};

   440 public:

   441 	/** Constructs an uninitialised TDbCol. It is necessary because there are 

   442 	also non-default constructors in this class. */

   443 	inline TDbCol() {}

   444 	inline TDbCol(const TDbCol&);

   445 	inline TDbCol& operator=(const TDbCol&);

   446 	IMPORT_C TDbCol(const TDesC& aName,TDbColType aType);

   447 	IMPORT_C TDbCol(const TDesC& aName,TDbColType aType,TInt aMaxLength);

   448 	static inline TBool IsLong(TDbColType aType);

   449 private:

   450 	inline TDbCol(const TDesC& aName);

   451 public:

   452 	/** The column type. */

   453 	TDbColType iType;

   454 	/** The maximum length of data that can be stored in a Text or Binary 

   455 	column. */

   456 	TInt iMaxLength;

   457 	/** A set of flags describing other column attributes. This must be one 

   458 	of the anonymous enum values ENotNull or EAutoIncrement. */

   459 	TUint iAttributes;

   460 	/** The column name. */

   461 	TDbColNameC iName;

   462 	};

   463 

   464 /** Manages a set of column definitions which describe a table or rowset 

   465 structure. Column definitions can be added and removed. The set can be 

   466 iterated over, and ordinals for a column can be looked up.

   467 

   468 The class is not intended for user derivation. 

   469 @publishedAll

   470 @released

   471 */

   472 class CDbColSet : public CBase

   473 	{

   474 	friend class TDbColSetIter;

   475 public:

   476 	IMPORT_C CDbColSet();

   477 	IMPORT_C static CDbColSet* NewL();

   478 	IMPORT_C static CDbColSet* NewLC();

   479 	IMPORT_C ~CDbColSet();

   480 	inline const TDbCol& operator[](TDbColNo aCol) const;

   481 	IMPORT_C const TDbCol* Col(const TDesC& aColName) const;

   482 	IMPORT_C TDbColNo ColNo(const TDesC& aColName) const;

   483 	inline TInt Count() const;

   484 	inline void Clear();

   485 	IMPORT_C CDbColSet& AddL(const TDbCol& aCol);

   486 	IMPORT_C void Remove(const TDesC& aColName);

   487 private:

   488 	CArrayPakFlat<TDbCol> iColumns;

   489 	};

   490 

   491 /** 

   492 Provides a useful way to iterate over the contents of a column set. 

   493 @publishedAll

   494 @released

   495 */

   496 class TDbColSetIter

   497 	{

   498 public:

   499 	IMPORT_C TDbColSetIter(const CDbColSet& aColSet);

   500 	inline operator TAny* () const;

   501 	inline const TDbCol& operator*() const;

   502 	inline const TDbCol* operator->() const;

   503 	IMPORT_C TDbColSetIter& operator++();

   504 	inline TDbColSetIter operator++(TInt);

   505 	inline TDbColNo Col() const;

   506 private:

   507 	const TDbCol* iColumn;

   508 	TInt iIndex;

   509 	const CArrayPakFlat<TDbCol>* iArray;

   510 	};

   511 

   512 /** Defines a key column in an index.

   513 

   514 The data members are public as this is really a structure to group the 

   515 attributes of the key column together. Two non-default constructors are 

   516 provided for convenience. 

   517 @publishedAll

   518 @released

   519 */

   520 class TDbKeyCol

   521 	{

   522 public:

   523 	/** Specifies whether a key column in an index should be sorted in 

   524 	ascending or descending order. */

   525 	enum TOrder 

   526 		{

   527 		/** Use ascending order. */

   528 		EAsc,

   529 		/** Use descending order. */

   530 		EDesc

   531 		};

   532 public:

   533 	/** Constructs an uninitialised object. Default constructor. It is necessary 

   534 	because there are also non-default constructors in this class. */

   535 	inline TDbKeyCol() {}

   536 	inline TDbKeyCol(const TDbKeyCol&);

   537 	inline TDbKeyCol& operator=(const TDbKeyCol&);

   538 	IMPORT_C TDbKeyCol(const TDesC& aName,TOrder anOrder=EAsc);

   539 	IMPORT_C TDbKeyCol(const TDesC& aName,TInt aLength,TOrder anOrder=EAsc);

   540 public:

   541 	/** The ordering of the key. */

   542 	TOrder iOrder;

   543 	/** The maximum number of characters used to index Text or LongText 

   544 	columns. If equal to KDbUndefinedLength (the default), all the characters 

   545 	in the defined column will be used. */

   546 	TInt iLength;

   547 	/** The column name for the key. */

   548 	TDbColNameC iName;

   549 	};

   550 

   551 /** 

   552 Represents the definition of an index. The key may be unique or primary, it 

   553 can specify the sort of comparison which is made for Text columns, and it 

   554 has a list of columns which make up the key. The class is used to construct 

   555 and interrogate index keys.

   556 

   557 This class is not intended for user derivation. 

   558 @publishedAll

   559 @released

   560 */

   561 class CDbKey : public CBase

   562 	{

   563 public:

   564 	enum {EUnique=0x01,EPrimary=0x02};

   565 public:

   566 	IMPORT_C CDbKey();

   567 	IMPORT_C static CDbKey* NewL();

   568 	IMPORT_C static CDbKey* NewLC();

   569 	IMPORT_C ~CDbKey();

   570 	IMPORT_C CDbKey& AddL(const TDbKeyCol& aKeyCol);

   571 	IMPORT_C void Remove(const TDesC& aColName);

   572 	IMPORT_C void Clear();

   573 	inline TInt Count() const;

   574 	inline const TDbKeyCol& operator[](TInt aCol) const;

   575 	inline void MakeUnique();

   576 	inline TBool IsUnique() const;

   577 	inline void SetComparison(TDbTextComparison aComparison);

   578 	inline TDbTextComparison Comparison() const;

   579 	inline void MakePrimary();

   580 	inline TBool IsPrimary() const;

   581 private:

   582 	CArrayPakFlat<TDbKeyCol> iKeys;

   583 	TDbTextComparison iComparison;

   584 	TInt iAttributes;

   585 	};

   586 

   587 /** 

   588 Saves the current location of a rowset, enabling rapid navigation back to a 

   589 previously visited row or position in the set.

   590 

   591 Instances of this class are returned by RDbRowSet::Bookmark(), which can later 

   592 be passed to RDbRowSet::GotoL() to return to the row which was current at 

   593 the call to Bookmark().

   594 

   595 @see RDbRowSet::Bookmark()

   596 @see RDbRowSet::GotoL() 

   597 @publishedAll

   598 @released

   599 */

   600 class TDbBookmark

   601 	{

   602 	friend class RDbRowSet;

   603 public:

   604 	struct TMark

   605 	/** Stores a database bookmark. */

   606 		{

   607 		enum {ESize=8};

   608 		TUint32 iMark[ESize];

   609 		};

   610 private:

   611 	TMark iMark;

   612 	};

   613 

   614 /** 

   615 A wrapper for an SQL string combined with a text comparison mode.

   616 

   617 An instance of the class is used as a parameter to RDbView::Prepare(), 

   618 RDbRowSet::FindL() and RDbRowConstraint::Open().

   619 

   620 The evaluation of SQL queries or constraints depends on how Text columns are 

   621 compared so every SQL string is accompanied by a member of the TDbTextComparison 

   622 enumeration to indicate how comparison is done.

   623 

   624 If the SQL string contains a LIKE clause with * (asterisks) wildcard then the 

   625 characters between them must be no longer than length 255.

   626 If only one * exists then the length is taken from the start and to the end of

   627 the clause. However, if the clause contains a ? (question mark) wildcard

   628 within it then the characters between must be no longer than length 253. 

   629 

   630 @see TDbTextComparison

   631 @see RDbView::Prepare()

   632 @see RDbRowSet::FindL()

   633 @see RDbRowConstraint::Open() 

   634 @publishedAll

   635 @released

   636 */

   637 class TDbQuery

   638 	{

   639 public:

   640 	inline TDbQuery(const TDesC& aQuery,TDbTextComparison aComparison=EDbCompareNormal);

   641 	inline const TDesC& Query() const;

   642 	inline TDbTextComparison Comparison() const;

   643 private:

   644 	const TDesC& iQuery;

   645 	TDbTextComparison iComparison;

   646 	};

   647 

   648 /** 

   649 This class is internal and is not intended for use 

   650 @publishedAll

   651 @released

   652 */

   653 class RDbHandleBase

   654 	{

   655 public:

   656 	inline RDbHandleBase();

   657 	void Close();

   658 protected:

   659 	inline void Set(CDbObject* aObject);

   660 	CDbObject& Object() const;

   661 protected:

   662 	CDbObject* iObject;

   663 	};

   664 

   665 /** 

   666 This class is internal and is not intended for use. 

   667 @publishedAll

   668 @released

   669 */

   670 template <class T>

   671 class RDbHandle : public RDbHandleBase

   672 	{

   673 public:

   674 	inline T* operator=(T* aT);

   675 	inline T* operator->() const;

   676 	inline T& operator*() const;

   677 	inline T* operator()() const;

   678 	};

   679 

   680 /** 

   681 Represents a pre-compiled SQL search-condition, which can be used to 

   682 test against the current row in a rowset.

   683 

   684 The constraint is compiled against a specific rowset, and can only be matched 

   685 against the same rowset using the RDbRowSet::MatchL() function.

   686 

   687 @see RDbRowSet 

   688 @publishedAll

   689 @released

   690 */

   691 class RDbRowConstraint

   692 	{

   693 	friend class RDbRowSet;

   694 public:

   695 	IMPORT_C TInt Open(const RDbRowSet& aView,TDbQuery aCriteria);

   696 	IMPORT_C void Close();

   697 private:

   698 	RDbHandle<CDbRowConstraint> iConstraint;

   699 	};

   700 

   701 /** 

   702 An abstract base class that provides functionality which is shared between 

   703 SQL view objects and Table objects. This functionality includes most of the 

   704 cursor navigation, row retrieval and update behaviour of rowsets.

   705 

   706 Rowset objects do not provide the data for the rowset on which they operate. 

   707 It is the responsibility of the derived classes RDbView and RDbTable to specify 

   708 the data source.

   709 

   710 This class is not intended for user derivation. 

   711 @publishedAll

   712 @released

   713 */

   714 class RDbRowSet

   715 	{

   716 	friend class RDbRowConstraint;

   717 	friend class RDbColReadStream;

   718 	friend class RDbColWriteStream;

   719 public:

   720 	/** Specifies where the rowset should navigate to in the GotoL() function. 

   721 	Their use is encapsulated by the respective member functions FirstL(), 

   722 	NextL() etc. */

   723 	enum TPosition 

   724 		{

   725 		/** Move to the first row in the rowset. */

   726 		EFirst,

   727 		/** Move to the next row in the rowset. */

   728 		ENext,

   729 		/** Move to the previous row in the rowset. */

   730 		EPrevious,

   731 		/** Move to the last row in the rowset. */

   732 		ELast,

   733 		/** Move to the position before the first row in the rowset. */

   734 		EBeginning,

   735 		/** Move to the position after the last row in the rowset. */

   736 		EEnd

   737 		};

   738 

   739 	/** Specifies which operations can be performed on a rowset. */

   740 	enum TAccess 

   741 		{

   742 		/** All operations can be performed on the rowset. */

   743 		EUpdatable,

   744 		/** Row navigation and reading are permitted. */

   745 		EReadOnly,

   746 		/** Inserting new rows is the only valid operation on the rowset. */

   747 		EInsertOnly

   748 		};

   749 

   750 	/** Specifies the direction to search through the rowset when using the 

   751 	FindL() function. */

   752 	enum TDirection 

   753 		{

   754 		/** Search from the current row forwards through the set. */

   755 		EForwards,

   756 		/** Search from the current row backwards through the set. */

   757 		EBackwards

   758 		};

   759 

   760 	/** Specifies whether the CountL() function should ensure that it returns 

   761 	the exact value which may be a non-trivial task. */

   762 	enum TAccuracy 

   763 		{

   764 		/** Take the time, if necessary, to return the exact value. */

   765 		EEnsure,

   766 		/** Return any immediately available value. */

   767 		EQuick

   768 		};

   769 public:

   770 	IMPORT_C void Close();

   771 	IMPORT_C void Reset();

   772 //

   773 	IMPORT_C CDbColSet* ColSetL() const;

   774 	IMPORT_C TInt ColCount() const;

   775 	IMPORT_C TDbColType ColType(TDbColNo aCol) const;

   776 	IMPORT_C TDbCol ColDef(TDbColNo aCol) const;

   777 //

   778 	IMPORT_C TBool AtRow() const;

   779 	IMPORT_C TBool AtBeginning() const;

   780 	IMPORT_C TBool AtEnd() const;

   781 //

   782 	IMPORT_C TInt CountL(TAccuracy anAccuracy=EEnsure) const;

   783 	IMPORT_C TBool IsEmptyL() const;

   784 //

   785 	IMPORT_C TBool GotoL(TPosition aPosition);

   786 	inline void BeginningL();

   787 	inline void EndL();

   788 	inline TBool FirstL();

   789 	inline TBool LastL();

   790 	inline TBool NextL();

   791 	inline TBool PreviousL();

   792 //

   793 	IMPORT_C TDbBookmark Bookmark() const;

   794 	IMPORT_C void GotoL(const TDbBookmark& aMark);

   795 //

   796 	IMPORT_C TBool MatchL(const RDbRowConstraint& aConstraint);

   797 	IMPORT_C TInt FindL(TDirection aDirection,TDbQuery aCriteria);

   798 //

   799 	IMPORT_C void GetL();

   800 	IMPORT_C void InsertL();

   801 	IMPORT_C void InsertCopyL();

   802 	IMPORT_C void UpdateL();

   803 	IMPORT_C void PutL();

   804 	IMPORT_C void Cancel();

   805 	IMPORT_C void DeleteL();

   806 //

   807 	inline TBool IsColNull(TDbColNo aCol) const;

   808 	IMPORT_C TInt ColSize(TDbColNo aCol) const;

   809 	IMPORT_C TInt ColLength(TDbColNo aCol) const;

   810 //

   811 	IMPORT_C TInt8 ColInt8(TDbColNo aCol) const;

   812 	IMPORT_C TInt16 ColInt16(TDbColNo aCol) const;

   813 	IMPORT_C TInt32 ColInt32(TDbColNo aCol) const;

   814 	IMPORT_C TInt64 ColInt64(TDbColNo aCol) const;

   815 	inline TInt ColInt(TDbColNo aCol) const;

   816 	IMPORT_C TUint8 ColUint8(TDbColNo aCol) const;

   817 	IMPORT_C TUint16 ColUint16(TDbColNo aCol) const;

   818 	IMPORT_C TUint32 ColUint32(TDbColNo aCol) const;

   819 	inline TUint ColUint(TDbColNo aCol) const;

   820 	IMPORT_C TReal32 ColReal32(TDbColNo aCol) const __SOFTFP;

   821 	IMPORT_C TReal64 ColReal64(TDbColNo aCol) const __SOFTFP;

   822 	inline TReal ColReal(TDbColNo aCol) const;

   823 	IMPORT_C TTime ColTime(TDbColNo aCol) const;

   824 	IMPORT_C TPtrC8 ColDes8(TDbColNo aCol) const;

   825 	IMPORT_C TPtrC16 ColDes16(TDbColNo aCol) const;

   826 	IMPORT_C TPtrC ColDes(TDbColNo aCol) const;

   827 //

   828 	IMPORT_C void SetColNullL(TDbColNo aCol);

   829 	inline void SetColL(TDbColNo aCol,TInt aValue);

   830 	IMPORT_C void SetColL(TDbColNo aCol,TInt32 aValue);

   831 	IMPORT_C void SetColL(TDbColNo aCol,TInt64 aValue);

   832 	inline void SetColL(TDbColNo aCol,TUint aValue);

   833 	IMPORT_C void SetColL(TDbColNo aCol,TUint32 aValue);

   834 	IMPORT_C void SetColL(TDbColNo aCol,TReal32 aValue) __SOFTFP;

   835 	IMPORT_C void SetColL(TDbColNo aCol,TReal64 aValue) __SOFTFP;

   836 	IMPORT_C void SetColL(TDbColNo aCol,TTime aValue);

   837 	IMPORT_C void SetColL(TDbColNo aCol,const TDesC8& aValue);

   838 	IMPORT_C void SetColL(TDbColNo aCol,const TDesC16& aValue);

   839 private:

   840 	inline MStreamBuf* ColSourceL(TDbColNo aCol) const;

   841 	inline MStreamBuf* ColSinkL(TDbColNo aCol);

   842 	CDbCursor& CheckCol(TDbColNo aCol) const;

   843 	TDbColumnC ColumnC(TDbColNo aCol,TDbColType aType) const;

   844 	TDbColumn Column(TDbColNo aCol,TDbColType aType);

   845 protected:

   846 	RDbHandle<CDbCursor> iCursor;

   847 	};

   848 

   849 /** 

   850 Allows any column value to be read as stream data.

   851 

   852 Note that this is the only way to extract the contents of a Long column from 

   853 a rowset.

   854 

   855 Only one column in a rowset object can be opened for reading as a stream at 

   856 a time, and while it is open no column in the same rowset object may be set 

   857 using RDbColWriteStream.

   858 

   859 Null columns result in a read stream with no data. Small numeric columns are 

   860 maintained in memory as 32-bit values; hence reading a Uint8 column as a stream 

   861 results in 4 bytes of stream data, not 1. 

   862 @publishedAll

   863 @released

   864 */

   865 class RDbColReadStream : public RReadStream

   866 	{

   867 public:

   868 	IMPORT_C void OpenL(const RDbRowSet& aView,TDbColNo aCol);

   869 	IMPORT_C void OpenLC(const RDbRowSet& aView,TDbColNo aCol);

   870 	};

   871 

   872 /** 

   873 Writes Long columns when inserting or updating rows in a rowset. 

   874 

   875 Only one column in a rowset object can be opened for writing as a stream at 

   876 a time. 

   877 @publishedAll

   878 @released

   879 */

   880 class RDbColWriteStream : public RWriteStream

   881 	{

   882 public:

   883 	/** Constructs this object by invoking the default constructor for 

   884 	RWriteStream. */

   885 	inline RDbColWriteStream() {}

   886 	inline RDbColWriteStream(const MExternalizer<TStreamRef> &anExternalizer);

   887 	IMPORT_C void OpenL(RDbRowSet& aView,TDbColNo aCol);

   888 	IMPORT_C void OpenLC(RDbRowSet& aView,TDbColNo aCol);

   889 	};

   890 

   891 /** 

   892 Describes the desired shape of a view's pre-evaluation window.

   893 

   894 An instance of this class is passed to the RDbView object as part of the 

   895 Prepare() function. The different constructors for TDbWindow can specify a view:

   896 

   897 without pre-evaluation

   898 

   899 with full pre-evaluation

   900 

   901 with limited pre-evaluation.

   902 

   903 @see RDbView 

   904 @publishedAll

   905 @released

   906 */

   907 class TDbWindow

   908 	{

   909 public:

   910 	/** Denotes a full pre-evaluation window. */

   911 	enum TUnlimited 

   912 		{

   913 		/** No limit on how many rows may be in the window. */

   914 		EUnlimited=KMaxTInt

   915 		};

   916 	enum {ENone=0};

   917 public:

   918 	inline TDbWindow();

   919 	inline TDbWindow(TUnlimited);

   920 	IMPORT_C TDbWindow(TInt aForeSlots,TInt aRearSlots);

   921 	inline TInt Size() const;

   922 	inline TInt PreferredPos() const;

   923 private:

   924 	TInt iSize;

   925 	TInt iPreferredPos;

   926 	};

   927 #if defined(__NO_CLASS_CONSTS__)

   928 /**

   929 @internalComponent

   930 */

   931 #define KDbUnlimitedWindow TDbWindow(TDbWindow::EUnlimited)

   932 #else

   933 /**

   934 @publishedAll

   935 @released

   936 */

   937 const TDbWindow KDbUnlimitedWindow=TDbWindow(TDbWindow::EUnlimited);

   938 #endif

   939 

   940 /** 

   941 Generates rowsets from an SQL query. The query is prepared and evaluated 

   942 using the interface to this class, while the rowset is manipulated using the 

   943 RDbRowset base class.

   944 

   945 There are no special rules to consider when deriving from this class. 

   946 @publishedAll

   947 @released

   948 */

   949 class RDbView : public RDbRowSet

   950 	{

   951 public:

   952 	IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,TAccess anAccess=EUpdatable);

   953 	IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow);

   954 	IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow,TAccess anAccess);

   955 	IMPORT_C TInt EvaluateAll();

   956 	IMPORT_C TInt Evaluate();

   957 	IMPORT_C void Evaluate(TRequestStatus& aStatus);

   958 	IMPORT_C TBool Unevaluated() const;

   959 	};

   960 

   961 /** 

   962 This class is internal and is not intended for use. 

   963 @publishedAll

   964 @released

   965 */

   966 template <class T>

   967 class TUnion

   968 	{

   969 public:

   970 	inline operator const T&() const;

   971 	inline const T& operator()() const;

   972 	inline T& operator()();

   973 	inline void Set(const T& aT);

   974 private:

   975 	TUint8 iRep[sizeof(T)];

   976 	};

   977 

   978 /** 

   979 This class is internal and is not intended for use. 

   980 @publishedAll

   981 @released

   982 */

   983 class TDbLookupKey

   984 	{

   985 public:

   986 	struct SColumn

   987 		{

   988 		union

   989 			{

   990 			TInt32 iInt32;

   991 			TUint32 iUint32;

   992 			TUnion<TInt64> iInt64;

   993 			TReal32 iReal32;

   994 			TReal64 iReal64;

   995 			TUnion<TTime> iTime;

   996 			struct {const TText8* iPtr;TInt iLength;} iDes8;

   997 			struct {const TText16* iPtr;TInt iLength;} iDes16;

   998 			};

   999 		TDbColType iType;

  1000 		};

  1001 public:

  1002 	inline TDbLookupKey();

  1003 	inline TInt Count() const;

  1004 	inline const SColumn* First() const;

  1005 	void Add(TInt aKey);

  1006 	void Add(TUint aKey);

  1007 	void Add(TInt64 aKey);

  1008 	void Add(TReal32 aKey) __SOFTFP;

  1009 	void Add(TReal64 aKey) __SOFTFP;

  1010 	void Add(TTime aKey);

  1011 	void Add(const TDesC8& aKey);

  1012 	void Add(const TDesC16& aKey);

  1013 private:

  1014 	SColumn& NextKey();

  1015 private:

  1016 	TInt iCount;

  1017 	SColumn iKey[1];	// at least one

  1018 	};

  1019 

  1020 /** 

  1021 Database key value.

  1022 

  1023 The class encapsulates a key value which is passed to RDbTable::SeekL(), for 

  1024 lookup in the currently active index on that rowset.

  1025 

  1026 An instance of this class can store a key value of any type.

  1027 

  1028 Note that the class can only hold a single-column key. Use TDbSeekMultiKey 

  1029 for multi-column keys.

  1030 

  1031 @see TDbSeekMultiKey

  1032 @see RDbTable 

  1033 @publishedAll

  1034 @released

  1035 */

  1036 class TDbSeekKey

  1037 	{

  1038 	friend class RDbTable;

  1039 public:

  1040 	inline TDbSeekKey();

  1041 	inline TDbSeekKey(TInt aKey);

  1042 	inline TDbSeekKey(TUint aKey);

  1043 	inline TDbSeekKey(TInt64 aKey);

  1044 	inline TDbSeekKey(TReal32 aKey);

  1045 	inline TDbSeekKey(TReal64 aKey);

  1046 	inline TDbSeekKey(TTime aKey);

  1047 	inline TDbSeekKey(const TDesC8& aKey);

  1048 	inline TDbSeekKey(const TDesC16& aKey);

  1049 	IMPORT_C TDbSeekKey& Add(TInt aKey);

  1050 	IMPORT_C TDbSeekKey& Add(TUint aKey);

  1051 	IMPORT_C TDbSeekKey& Add(TInt64 aKey);

  1052 	IMPORT_C TDbSeekKey& Add(TReal32 aKey) __SOFTFP;

  1053 	IMPORT_C TDbSeekKey& Add(TReal64 aKey) __SOFTFP;

  1054 	IMPORT_C TDbSeekKey& Add(TTime aKey);

  1055 	IMPORT_C TDbSeekKey& Add(const TDesC8& aKey);

  1056 	IMPORT_C TDbSeekKey& Add(const TDesC16& aKey);

  1057 private:

  1058 	TDbLookupKey& Check();

  1059 protected:

  1060 	inline TDbSeekKey(TInt aKeys,TInt);

  1061 private:

  1062 	TInt iMaxKeys;

  1063 	TDbLookupKey iKey;

  1064 	};

  1065 

  1066 /** 

  1067 Database multi-column key value.

  1068 

  1069 The class extends the behaviour of TDbSeekKey by allowing multi-column indexes 

  1070 to be searched using multi-column key values.

  1071 

  1072 The template parameter S specifies the maximum number of column values that 

  1073 can be added to the key value.

  1074 

  1075 Use the TDbSeekKey::Add() members to append the values for each column in 

  1076 the key value. 

  1077 @publishedAll

  1078 @released

  1079 */

  1080 template<TInt S>

  1081 class TDbSeekMultiKey : public TDbSeekKey

  1082 	{

  1083 public:

  1084 	inline TDbSeekMultiKey();

  1085 private:

  1086 	TDbLookupKey::SColumn iExtraKeys[S-1];

  1087 	};

  1088 

  1089 /** 

  1090 Provides access to table data as a rowset, allowing manipulation of a named 

  1091 table in the database. Additionally, a named index can be used to order the 

  1092 rowset, and to provide fast key-based row retrieval from the table.

  1093 

  1094 There are no special rules to consider when deriving from this class. 

  1095 @publishedAll

  1096 @released

  1097 */

  1098 class RDbTable : public RDbRowSet

  1099 	{

  1100 public:

  1101 	/** Database table seek comparison types. */

  1102 	enum TComparison 

  1103 		{

  1104 		/** Retrieve the last row which is strictly less than the key value. */

  1105 		ELessThan,

  1106 		/** Retrieve the last row which is equal to or less than the key 

  1107 		value. */

  1108 		ELessEqual,

  1109 		/** Retrieve the first row which is equal to the key value. */

  1110 		EEqualTo,

  1111 		/** Retrieve the first row which is equal to or greater than the key 

  1112 		value. */

  1113 		EGreaterEqual,

  1114 		/** Retrieve the first row which is strictly greater than the key 

  1115 		value. */

  1116 		EGreaterThan

  1117 		};

  1118 public:

  1119 	IMPORT_C TInt Open(RDbDatabase& aDatabase,const TDesC& aName,TAccess anAccess=EUpdatable);

  1120 	inline TInt SetIndex(const TDesC& anIndex);

  1121 	inline TInt SetNoIndex();

  1122 	IMPORT_C TBool SeekL(const TDbSeekKey& aKey,TComparison aComparison=EEqualTo);

  1123 private:

  1124 	IMPORT_C TInt SetIndex(const TDesC* anIndex);

  1125 	};

  1126 

  1127 /**

  1128 @publishedAll

  1129 @released

  1130 */

  1131 class CDbNames : public CBase

  1132 	{

  1133 private:

  1134 	inline CDbNames();