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 "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.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 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS 

    27 	#include <d32dbmsconstants.h>

    28 #endif

    29 

    30 // other classes referenced

    31 class RFs;

    32 class CDbObject;

    33 class CDbRowConstraint;

    34 class CDbCursor;

    35 class CDbDatabase;

    36 class CDbIncremental;

    37 class CDbNotifier;

    38 class TDbColumn;

    39 class TDbColumnC;

    40 

    41 // classes defined

    42 class TDbCol;

    43 class CDbColSet;

    44 class TDbColSetIter;

    45 class TDbKeyCol;

    46 class CDbKey;

    47 class TDbBookmark;

    48 class TDbQuery;

    49 class RDbHandleBase;

    50 template<class T> class RDbHandle;

    51 class RDbRowConstraint;

    52 class RDbRowSet;

    53 class RDbColReadStream;

    54 class RDbColWriteStream;

    55 class TDbWindow;

    56 class RDbView;

    57 template<class T> class TUnion;

    58 class TDbLookupKey;

    59 class TDbSeekKey;

    60 template<TInt S> class TDbSeekMultiKey;

    61 class RDbTable;

    62 class CDbNames;

    63 class RDbDatabase;

    64 class RDbIncremental;

    65 class RDbUpdate;

    66 class RDbNotifier;

    67 class RDbs;

    68 class RDbNamedDatabase;

    69 class RDbStoreDatabase;

    70 

    71 /**

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

    73 @publishedAll

    74 @released

    75 */

    76 const TInt KDbMaxName=0x40;

    77 

    78 /**

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

    80 @publishedAll

    81 @released

    82 */

    83 const TInt KDbMaxColName=KDbMaxName;

    84 

    85 /** 

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

    87 with maximum size KDbMaxName.

    88 

    89 Notes:

    90 

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

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

    93 to 64 characters in length.

    94 

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

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

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

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

    99 same name.

   100 

   101 @see TBuf 

   102 @publishedAll

   103 @released

   104 */

   105 typedef TBuf<KDbMaxName> TDbName;

   106 

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

   108 with maximum size KDbMaxName.

   109 

   110 Notes:

   111 

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

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

   114 to 64 characters in length.

   115 

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

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

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

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

   120 same name.

   121 

   122 @see TBufC 

   123 @publishedAll

   124 @released

   125 */

   126 typedef TBufC<KDbMaxName> TDbNameC;

   127 

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

   129 with maximum size KDbMaxColName.

   130 

   131 Notes:

   132 

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

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

   135 to 64 characters in length.

   136 

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

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

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

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

   141 same name. 

   142 @publishedAll

   143 @released

   144 */

   145 typedef TBuf<KDbMaxColName> TDbColName;

   146 

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

   148 descriptor with maximum size KDbMaxColName.

   149 

   150 Notes:

   151 

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

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

   154 to 64 characters in length.

   155 

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

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

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

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

   160 same name.

   161 

   162 @see TBufC 

   163 @publishedAll

   164 @released

   165 */

   166 typedef TBufC<KDbMaxColName> TDbColNameC;

   167 

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

   169 a column set or in a rowset.

   170 

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

   172 no such column exists. 

   173 @publishedAll

   174 @released

   175 */

   176 typedef TInt TDbColNo;

   177 

   178 /** 

   179 Indicates that a specified column does not exist. 

   180 @publishedAll

   181 @released

   182 */

   183 const TDbColNo KDbNullColNo=0;

   184 

   185 /** 

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

   187 

   188 @see RDbRowSet 

   189 @publishedAll

   190 @released

   191 */

   192 const TInt KDbUndefinedCount=-1;

   193 

   194 /** 

   195 The length of a column is undefined. 

   196 @publishedAll

   197 @released

   198 */

   199 const TInt KDbUndefinedLength=-1;

   200 

   201 /** 

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

   203 @publishedAll

   204 @released

   205 */

   206 const TInt KDbDefaultTextColLength=50;

   207 

   208 /** 

   209 Represents every supported column type. 

   210 @publishedAll

   211 @released

   212 */

   213 enum TDbColType

   214 	{

   215 	/** The column stores a single bit.

   216 	

   217 	Representation range: 0 to 1

   218 	

   219 	Storage: 1 bit

   220 	

   221 	Auto-increment: Yes

   222 	

   223 	Index key: Yes */

   224 	EDbColBit,

   225 

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

   227 	

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

   229 	

   230 	Storage: 1 byte

   231 	

   232 	Auto-increment: Yes

   233 	

   234 	Index key: Yes */

   235 	EDbColInt8,

   236 

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

   238 	

   239 	Representation range: 0 to 2^8-1

   240 	

   241 	Storage: 1 byte

   242 	

   243 	Auto-increment: Yes

   244 	

   245 	Index key: Yes */

   246 	EDbColUint8,

   247 

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

   249 	

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

   251 	

   252 	Storage: 2 bytes

   253 	

   254 	Auto-increment: Yes

   255 	

   256 	Index key: Yes */

   257 	EDbColInt16,

   258 

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

   260 	

   261 	Representation range: 0 to 2^16-1

   262 	

   263 	Storage: 2 bytes

   264 	

   265 	Auto-increment: Yes

   266 	

   267 	Index key: Yes */

   268 	EDbColUint16,

   269 

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

   271 	

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

   273 	

   274 	Storage: 4 bytes

   275 	

   276 	Auto-increment: Yes

   277 	

   278 	Index key: Yes */

   279 	EDbColInt32,

   280 

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

   282 	

   283 	Representation range: 0 to 2^32-1

   284 	

   285 	Storage: 4 bytes

   286 	

   287 	Auto-increment: Yes

   288 	

   289 	Index key: Yes */

   290 	EDbColUint32,

   291 

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

   293 	

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

   295 	

   296 	Storage: 8 bytes

   297 	

   298 	Auto-increment: No

   299 	

   300 	Index key: Yes */

   301 	EDbColInt64,

   302 

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

   304 	

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

   306 	

   307 	Storage: 4 bytes

   308 	

   309 	Auto-increment: No

   310 	

   311 	Index key: Yes */

   312 	EDbColReal32,

   313 

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

   315 	

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

   317 	

   318 	Storage: 8 bytes

   319 	

   320 	Auto-increment: No

   321 	

   322 	Index key: Yes */

   323 	EDbColReal64,

   324 

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

   326 	

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

   328 	

   329 	Storage: 8 bytes

   330 	

   331 	Auto-increment: No

   332 	

   333 	Index key: Yes */

   334 	EDbColDateTime,

   335 

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

   337 	

   338 	Representation range: 0 to 256 characters

   339 	

   340 	Storage: 0 to 256 bytes

   341 	

   342 	Auto-increment: No

   343 	

   344 	Index key: Yes */

   345 	EDbColText8,

   346 

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

   348 	

   349 	Representation range: 0 to 256 characters

   350 	

   351 	Storage: 0 to 512 bytes

   352 	

   353 	Auto-increment: No

   354 	

   355 	Index key: Yes */

   356 	EDbColText16,

   357 

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

   359 	

   360 	Representation range: 0 to 255 bytes

   361 	

   362 	Storage: 0 to 256 bytes

   363 	

   364 	Auto-increment: No

   365 	

   366 	Index key: No */

   367 	EDbColBinary,

   368 

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

   370 	

   371 	Representation range: 0 to 2^31 characters

   372 	

   373 	Storage: 0 to 2 Gbytes

   374 	

   375 	Auto-increment: No

   376 	

   377 	Index key: Truncated */

   378 	EDbColLongText8,

   379 

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

   381 	

   382 	Representation range: 0 to 2^30 characters

   383 	

   384 	Storage: 0 to 2 Gbytes

   385 	

   386 	Auto-increment: No

   387 	

   388 	Index key: Truncated */

   389 	EDbColLongText16,

   390 

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

   392 	

   393 	Representation range: 0 to 2^31 bytes

   394 	

   395 	Storage: 0 to 2 Gbytes

   396 	

   397 	Auto-increment: No

   398 	

   399 	Index key: No */

   400 	EDbColLongBinary,

   401 

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

   403 	EDbColText16 if the build is Unicode. */

   404 	EDbColText=EDbColText16,

   405 

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

   407 	EDbColLongText16 if the build is Unicode. */

   408 	EDbColLongText=EDbColLongText16

   409 	};

   410 

   411 /** 

   412 Represents different ways of comparing Text and LongText columns.

   413 

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

   415 queries and matching row constraints (see TDbQuery). 

   416 @publishedAll

   417 @released

   418 */

   419 enum TDbTextComparison 

   420 	{

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

   422 	EDbCompareNormal,

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

   424 	EDbCompareFolded,

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

   426 	EDbCompareCollated

   427 	};

   428 

   429 /** 

   430 Defines a column in a table or rowset. 

   431 

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

   433 attributes of the column together. 

   434 

   435 Three non-default constructors are provided for convenience. 

   436 @publishedAll

   437 @released

   438 */

   439 class TDbCol

   440 	{

   441 	friend class CDbColSet;

   442 public:

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

   444 public:

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

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

   447 	inline TDbCol() {}

   448 	inline TDbCol(const TDbCol&);

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

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

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

   452 	static inline TBool IsLong(TDbColType aType);

   453 private:

   454 	inline TDbCol(const TDesC& aName);

   455 public:

   456 	/** The column type. */

   457 	TDbColType iType;

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

   459 	column. */

   460 	TInt iMaxLength;

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

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

   463 	TUint iAttributes;

   464 	/** The column name. */

   465 	TDbColNameC iName;

   466 	};

   467 

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

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

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

   471 

   472 The class is not intended for user derivation. 

   473 @publishedAll

   474 @released

   475 */

   476 class CDbColSet : public CBase

   477 	{

   478 	friend class TDbColSetIter;

   479 public:

   480 	IMPORT_C CDbColSet();

   481 	IMPORT_C static CDbColSet* NewL();

   482 	IMPORT_C static CDbColSet* NewLC();

   483 	IMPORT_C ~CDbColSet();

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

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

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

   487 	inline TInt Count() const;

   488 	inline void Clear();

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

   490 	IMPORT_C void Remove(const TDesC& aColName);

   491 private:

   492 	CArrayPakFlat<TDbCol> iColumns;

   493 	};

   494 

   495 /** 

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

   497 @publishedAll

   498 @released

   499 */

   500 class TDbColSetIter

   501 	{

   502 public:

   503 	IMPORT_C TDbColSetIter(const CDbColSet& aColSet);

   504 	inline operator TAny* () const;

   505 	inline const TDbCol& operator*() const;

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

   507 	IMPORT_C TDbColSetIter& operator++();

   508 	inline TDbColSetIter operator++(TInt);

   509 	inline TDbColNo Col() const;

   510 private:

   511 	const TDbCol* iColumn;

   512 	TInt iIndex;

   513 	const CArrayPakFlat<TDbCol>* iArray;

   514 	};

   515 

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

   517 

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

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

   520 provided for convenience. 

   521 @publishedAll

   522 @released

   523 */

   524 class TDbKeyCol

   525 	{

   526 public:

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

   528 	ascending or descending order. */

   529 	enum TOrder 

   530 		{

   531 		/** Use ascending order. */

   532 		EAsc,

   533 		/** Use descending order. */

   534 		EDesc

   535 		};

   536 public:

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

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

   539 	inline TDbKeyCol() {}

   540 	inline TDbKeyCol(const TDbKeyCol&);

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

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

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

   544 public:

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

   546 	TOrder iOrder;

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

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

   549 	in the defined column will be used. */

   550 	TInt iLength;

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

   552 	TDbColNameC iName;

   553 	};

   554 

   555 /** 

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

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

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

   559 and interrogate index keys.

   560 

   561 This class is not intended for user derivation. 

   562 @publishedAll

   563 @released

   564 */

   565 class CDbKey : public CBase

   566 	{

   567 public:

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

   569 public:

   570 	IMPORT_C CDbKey();

   571 	IMPORT_C static CDbKey* NewL();

   572 	IMPORT_C static CDbKey* NewLC();

   573 	IMPORT_C ~CDbKey();

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

   575 	IMPORT_C void Remove(const TDesC& aColName);

   576 	IMPORT_C void Clear();

   577 	inline TInt Count() const;

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

   579 	inline void MakeUnique();

   580 	inline TBool IsUnique() const;

   581 	inline void SetComparison(TDbTextComparison aComparison);

   582 	inline TDbTextComparison Comparison() const;

   583 	inline void MakePrimary();

   584 	inline TBool IsPrimary() const;

   585 private:

   586 	CArrayPakFlat<TDbKeyCol> iKeys;

   587 	TDbTextComparison iComparison;

   588 	TInt iAttributes;

   589 	};

   590 

   591 /** 

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

   593 previously visited row or position in the set.

   594 

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

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

   597 the call to Bookmark().

   598 

   599 @see RDbRowSet::Bookmark()

   600 @see RDbRowSet::GotoL() 

   601 @publishedAll

   602 @released

   603 */

   604 class TDbBookmark

   605 	{

   606 	friend class RDbRowSet;

   607 public:

   608 	struct TMark

   609 	/** Stores a database bookmark. */

   610 		{

   611 		enum {ESize=8};

   612 		TUint32 iMark[ESize];

   613 		};

   614 private:

   615 	TMark iMark;

   616 	};

   617 

   618 /** 

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

   620 

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

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

   623 

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

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

   626 enumeration to indicate how comparison is done.

   627 

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

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

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

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

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

   633 

   634 @see TDbTextComparison

   635 @see RDbView::Prepare()

   636 @see RDbRowSet::FindL()

   637 @see RDbRowConstraint::Open() 

   638 @publishedAll

   639 @released

   640 */

   641 class TDbQuery

   642 	{

   643 public:

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

   645 	inline const TDesC& Query() const;

   646 	inline TDbTextComparison Comparison() const;

   647 private:

   648 	const TDesC& iQuery;

   649 	TDbTextComparison iComparison;

   650 	};

   651 

   652 /** 

   653 This class is internal and is not intended for use 

   654 @publishedAll

   655 @released

   656 */

   657 class RDbHandleBase

   658 	{

   659 public:

   660 	inline RDbHandleBase();

   661 	void Close();

   662 protected:

   663 	inline void Set(CDbObject* aObject);

   664 	CDbObject& Object() const;

   665 protected:

   666 	CDbObject* iObject;

   667 	};

   668 

   669 /** 

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

   671 @publishedAll

   672 @released

   673 */

   674 template <class T>

   675 class RDbHandle : public RDbHandleBase

   676 	{

   677 public:

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

   679 	inline T* operator->() const;

   680 	inline T& operator*() const;

   681 	inline T* operator()() const;

   682 	};

   683 

   684 /** 

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

   686 test against the current row in a rowset.

   687 

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

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

   690 

   691 @see RDbRowSet 

   692 @publishedAll

   693 @released

   694 */

   695 class RDbRowConstraint

   696 	{

   697 	friend class RDbRowSet;

   698 public:

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

   700 	IMPORT_C void Close();

   701 private:

   702 	RDbHandle<CDbRowConstraint> iConstraint;

   703 	};

   704 

   705 /** 

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

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

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

   709 

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

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

   712 the data source.

   713 

   714 This class is not intended for user derivation. 

   715 @publishedAll

   716 @released

   717 */

   718 class RDbRowSet

   719 	{

   720 	friend class RDbRowConstraint;

   721 	friend class RDbColReadStream;

   722 	friend class RDbColWriteStream;

   723 public:

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

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

   726 	NextL() etc. */

   727 	enum TPosition 

   728 		{

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

   730 		EFirst,

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

   732 		ENext,

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

   734 		EPrevious,

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

   736 		ELast,

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

   738 		EBeginning,

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

   740 		EEnd

   741 		};

   742 

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

   744 	enum TAccess 

   745 		{

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

   747 		EUpdatable,

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

   749 		EReadOnly,

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

   751 		EInsertOnly

   752 		};

   753 

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

   755 	FindL() function. */

   756 	enum TDirection 

   757 		{

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

   759 		EForwards,

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

   761 		EBackwards

   762 		};

   763 

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

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

   766 	enum TAccuracy 

   767 		{

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

   769 		EEnsure,

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

   771 		EQuick

   772 		};

   773 public:

   774 	IMPORT_C void Close();

   775 	IMPORT_C void Reset();

   776 //

   777 	IMPORT_C CDbColSet* ColSetL() const;

   778 	IMPORT_C TInt ColCount() const;

   779 	IMPORT_C TDbColType ColType(TDbColNo aCol) const;

   780 	IMPORT_C TDbCol ColDef(TDbColNo aCol) const;

   781 //

   782 	IMPORT_C TBool AtRow() const;

   783 	IMPORT_C TBool AtBeginning() const;

   784 	IMPORT_C TBool AtEnd() const;

   785 //

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

   787 	IMPORT_C TBool IsEmptyL() const;

   788 //

   789 	IMPORT_C TBool GotoL(TPosition aPosition);

   790 	inline void BeginningL();

   791 	inline void EndL();

   792 	inline TBool FirstL();

   793 	inline TBool LastL();

   794 	inline TBool NextL();

   795 	inline TBool PreviousL();

   796 //

   797 	IMPORT_C TDbBookmark Bookmark() const;

   798 	IMPORT_C void GotoL(const TDbBookmark& aMark);

   799 //

   800 	IMPORT_C TBool MatchL(const RDbRowConstraint& aConstraint);

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

   802 //

   803 	IMPORT_C void GetL();

   804 	IMPORT_C void InsertL();

   805 	IMPORT_C void InsertCopyL();

   806 	IMPORT_C void UpdateL();

   807 	IMPORT_C void PutL();

   808 	IMPORT_C void Cancel();

   809 	IMPORT_C void DeleteL();

   810 //

   811 	inline TBool IsColNull(TDbColNo aCol) const;

   812 	IMPORT_C TInt ColSize(TDbColNo aCol) const;

   813 	IMPORT_C TInt ColLength(TDbColNo aCol) const;

   814 //

   815 	IMPORT_C TInt8 ColInt8(TDbColNo aCol) const;

   816 	IMPORT_C TInt16 ColInt16(TDbColNo aCol) const;

   817 	IMPORT_C TInt32 ColInt32(TDbColNo aCol) const;

   818 	IMPORT_C TInt64 ColInt64(TDbColNo aCol) const;

   819 	inline TInt ColInt(TDbColNo aCol) const;

   820 	IMPORT_C TUint8 ColUint8(TDbColNo aCol) const;

   821 	IMPORT_C TUint16 ColUint16(TDbColNo aCol) const;

   822 	IMPORT_C TUint32 ColUint32(TDbColNo aCol) const;

   823 	inline TUint ColUint(TDbColNo aCol) const;

   824 	IMPORT_C TReal32 ColReal32(TDbColNo aCol) const __SOFTFP;

   825 	IMPORT_C TReal64 ColReal64(TDbColNo aCol) const __SOFTFP;

   826 	inline TReal ColReal(TDbColNo aCol) const;

   827 	IMPORT_C TTime ColTime(TDbColNo aCol) const;

   828 	IMPORT_C TPtrC8 ColDes8(TDbColNo aCol) const;

   829 	IMPORT_C TPtrC16 ColDes16(TDbColNo aCol) const;

   830 	IMPORT_C TPtrC ColDes(TDbColNo aCol) const;

   831 //

   832 	IMPORT_C void SetColNullL(TDbColNo aCol);

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

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

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

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

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

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

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

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

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

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

   843 private:

   844 	inline MStreamBuf* ColSourceL(TDbColNo aCol) const;

   845 	inline MStreamBuf* ColSinkL(TDbColNo aCol);

   846 	CDbCursor& CheckCol(TDbColNo aCol) const;

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

   848 	TDbColumn Column(TDbColNo aCol,TDbColType aType);

   849 protected:

   850 	RDbHandle<CDbCursor> iCursor;

   851 	};

   852 

   853 /** 

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

   855 

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

   857 a rowset.

   858 

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

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

   861 using RDbColWriteStream.

   862 

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

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

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

   866 @publishedAll

   867 @released

   868 */

   869 class RDbColReadStream : public RReadStream

   870 	{

   871 public:

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

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

   874 	};

   875 

   876 /** 

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

   878 

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

   880 a time. 

   881 @publishedAll

   882 @released

   883 */

   884 class RDbColWriteStream : public RWriteStream

   885 	{

   886 public:

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

   888 	RWriteStream. */

   889 	inline RDbColWriteStream() {}

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

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

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

   893 	};

   894 

   895 /** 

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

   897 

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

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

   900 

   901 without pre-evaluation

   902 

   903 with full pre-evaluation

   904 

   905 with limited pre-evaluation.

   906 

   907 @see RDbView 

   908 @publishedAll

   909 @released

   910 */

   911 class TDbWindow

   912 	{

   913 public:

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

   915 	enum TUnlimited 

   916 		{

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

   918 		EUnlimited=KMaxTInt

   919 		};

   920 	enum {ENone=0};

   921 public:

   922 	inline TDbWindow();

   923 	inline TDbWindow(TUnlimited);

   924 	IMPORT_C TDbWindow(TInt aForeSlots,TInt aRearSlots);

   925 	inline TInt Size() const;

   926 	inline TInt PreferredPos() const;

   927 private:

   928 	TInt iSize;

   929 	TInt iPreferredPos;

   930 	};

   931 

   932 #if defined(__NO_CLASS_CONSTS__)

   933 /**

   934 @publishedAll

   935 @released

   936 */

   937 #define KDbUnlimitedWindow TDbWindow(TDbWindow::EUnlimited)

   938 #else

   939 /**

   940 @publishedAll

   941 @released

   942 */

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

   944 #endif

   945 

   946 /** 

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

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

   949 RDbRowset base class.

   950 

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

   952 @publishedAll

   953 @released

   954 */

   955 class RDbView : public RDbRowSet

   956 	{

   957 public:

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

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

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

   961 	IMPORT_C TInt EvaluateAll();

   962 	IMPORT_C TInt Evaluate();

   963 	IMPORT_C void Evaluate(TRequestStatus& aStatus);

   964 	IMPORT_C TBool Unevaluated() const;

   965 	};

   966 

   967 /** 

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

   969 @publishedAll

   970 @released

   971 */

   972 template <class T>

   973 class TUnion

   974 	{

   975 public:

   976 	inline operator const T&() const;

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

   978 	inline T& operator()();

   979 	inline void Set(const T& aT);

   980 private:

   981 	TUint8 iRep[sizeof(T)];

   982 	};

   983 

   984 /** 

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

   986 @publishedAll

   987 @released

   988 */

   989 class TDbLookupKey

   990 	{

   991 public:

   992 	struct SColumn

   993 		{

   994 		union

   995 			{

   996 			TInt32 iInt32;

   997 			TUint32 iUint32;

   998 			TUnion<TInt64> iInt64;

   999 			TReal32 iReal32;

  1000 			TReal64 iReal64;

  1001 			TUnion<TTime> iTime;

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

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

  1004 			};

  1005 		TDbColType iType;

  1006 		};

  1007 public:

  1008 	inline TDbLookupKey();

  1009 	inline TInt Count() const;

  1010 	inline const SColumn* First() const;

  1011 	void Add(TInt aKey);

  1012 	void Add(TUint aKey);

  1013 	void Add(TInt64 aKey);

  1014 	void Add(TReal32 aKey) __SOFTFP;

  1015 	void Add(TReal64 aKey) __SOFTFP;

  1016 	void Add(TTime aKey);

  1017 	void Add(const TDesC8& aKey);

  1018 	void Add(const TDesC16& aKey);

  1019 private:

  1020 	SColumn& NextKey();

  1021 private:

  1022 	TInt iCount;

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

  1024 	};

  1025 

  1026 /** 

  1027 Database key value.

  1028 

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

  1030 lookup in the currently active index on that rowset.

  1031 

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

  1033 

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

  1035 for multi-column keys.

  1036 

  1037 @see TDbSeekMultiKey

  1038 @see RDbTable 

  1039 @publishedAll

  1040 @released

  1041 */

  1042 class TDbSeekKey

  1043 	{

  1044 	friend class RDbTable;

  1045 public:

  1046 	inline TDbSeekKey();

  1047 	inline TDbSeekKey(TInt aKey);

  1048 	inline TDbSeekKey(TUint aKey);

  1049 	inline TDbSeekKey(TInt64 aKey);

  1050 	inline TDbSeekKey(TReal32 aKey);

  1051 	inline TDbSeekKey(TReal64 aKey);

  1052 	inline TDbSeekKey(TTime aKey);

  1053 	inline TDbSeekKey(const TDesC8& aKey);

  1054 	inline TDbSeekKey(const TDesC16& aKey);

  1055 	IMPORT_C TDbSeekKey& Add(TInt aKey);

  1056 	IMPORT_C TDbSeekKey& Add(TUint aKey);

  1057 	IMPORT_C TDbSeekKey& Add(TInt64 aKey);

  1058 	IMPORT_C TDbSeekKey& Add(TReal32 aKey) __SOFTFP;

  1059 	IMPORT_C TDbSeekKey& Add(TReal64 aKey) __SOFTFP;

  1060 	IMPORT_C TDbSeekKey& Add(TTime aKey);

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

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

  1063 private:

  1064 	TDbLookupKey& Check();

  1065 protected:

  1066 	inline TDbSeekKey(TInt aKeys,TInt);

  1067 private:

  1068 	TInt iMaxKeys;

  1069 	TDbLookupKey iKey;

  1070 	};

  1071 

  1072 /** 

  1073 Database multi-column key value.

  1074 

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

  1076 to be searched using multi-column key values.

  1077 

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

  1079 can be added to the key value.

  1080 

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

  1082 the key value. 

  1083 @publishedAll

  1084 @released

  1085 */

  1086 template<TInt S>

  1087 class TDbSeekMultiKey : public TDbSeekKey

  1088 	{

  1089 public:

  1090 	inline TDbSeekMultiKey();

  1091 private:

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

  1093 	};

  1094 

  1095 /** 

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

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

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

  1099 

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

  1101 @publishedAll

  1102 @released

  1103 */

  1104 class RDbTable : public RDbRowSet

  1105 	{

  1106 public:

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

  1108 	enum TComparison 

  1109 		{

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

  1111 		ELessThan,

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

  1113 		value. */

  1114 		ELessEqual,

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

  1116 		EEqualTo,

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

  1118 		value. */

  1119 		EGreaterEqual,

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

  1121 		value. */

  1122 		EGreaterThan

  1123 		};

  1124 public:

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

  1126 	inline TInt SetIndex(const TDesC& anIndex);

  1127 	inline TInt SetNoIndex();

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

  1129 private:

  1130 	IMPORT_C TInt SetIndex(const TDesC* anIndex);

  1131 	};

  1132 

  1133 /**

  1134 @publishedAll

  1135 @released