// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// 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
// which accompanies this distribution, and is available
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//
#if !defined(__D32DBMS_H__)
#define __D32DBMS_H__
#ifndef __S32STD_H__
#include <s32std.h>
#endif
#ifndef __F32FILE_H__
#include <f32file.h>
#endif
// other classes referenced
class RFs;
class CDbObject;
class CDbRowConstraint;
class CDbCursor;
class CDbDatabase;
class CDbIncremental;
class CDbNotifier;
class TDbColumn;
class TDbColumnC;
// classes defined
class TDbCol;
class CDbColSet;
class TDbColSetIter;
class TDbKeyCol;
class CDbKey;
class TDbBookmark;
class TDbQuery;
class RDbHandleBase;
template<class T> class RDbHandle;
class RDbRowConstraint;
class RDbRowSet;
class RDbColReadStream;
class RDbColWriteStream;
class TDbWindow;
class RDbView;
template<class T> class TUnion;
class TDbLookupKey;
class TDbSeekKey;
template<TInt S> class TDbSeekMultiKey;
class RDbTable;
class CDbNames;
class RDbDatabase;
class RDbIncremental;
class RDbUpdate;
class RDbNotifier;
class RDbs;
class RDbNamedDatabase;
class RDbStoreDatabase;
/**
The maximum length for a DBMS name: 64 characters.
@publishedAll
@released
*/
const TInt KDbMaxName=0x40;
/**
The maximum length for a DBMS column name: 64 characters.
@publishedAll
@released
*/
const TInt KDbMaxColName=KDbMaxName;
/**
Represents a writable DBMS name. It maps to a modifiable buffer descriptor
with maximum size KDbMaxName.
Notes:
A DBMS name must begin with an alphabetic character, after which any alphabetic,
numeric or the _ (underscore) character may be used. DBMS names are also limited
to 64 characters in length.
Table names must be unique within a database, and columns and indexes must
have unique names within the table to which they belong. For the purposes
of uniqueness and identification, the names are folded before comparison,
so two columns named column_one and Column_ONE are considered to have the
same name.
@see TBuf
@publishedAll
@released
*/
typedef TBuf<KDbMaxName> TDbName;
/** Represents a non-writeable DBMS name. It maps to a non modifiable buffer descriptor
with maximum size KDbMaxName.
Notes:
A DBMS name must begin with an alphabetic character, after which any alphabetic,
numeric or the _ (underscore) character may be used. DBMS names are also limited
to 64 characters in length.
Table names must be unique within a database, and columns and indexes must
have unique names within the table to which they belong. For the purposes
of uniqueness and identification, the names are folded before comparison,
so two columns named column_one and Column_ONE are considered to have the
same name.
@see TBufC
@publishedAll
@released
*/
typedef TBufC<KDbMaxName> TDbNameC;
/** Represents a writable DBMS column name. It maps to a modifiable buffer descriptor
with maximum size KDbMaxColName.
Notes:
A DBMS name must begin with an alphabetic character, after which any alphabetic,
numeric or the _ (underscore) character may be used. DBMS names are also limited
to 64 characters in length.
Table names must be unique within a database, and columns and indexes must
have unique names within the table to which they belong. For the purposes
of uniqueness and identification, the names are folded before comparison,
so two columns named column_one and Column_ONE are considered to have the
same name.
@publishedAll
@released
*/
typedef TBuf<KDbMaxColName> TDbColName;
/** Represents a non-writable DBMS column name. It maps to a non-modifiable buffer
descriptor with maximum size KDbMaxColName.
Notes:
A DBMS name must begin with an alphabetic character, after which any alphabetic,
numeric or the _ (underscore) character may be used. DBMS names are also limited
to 64 characters in length.
Table names must be unique within a database, and columns and indexes must
have unique names within the table to which they belong. For the purposes
of uniqueness and identification, the names are folded before comparison,
so two columns named column_one and Column_ONE are considered to have the
same name.
@see TBufC
@publishedAll
@released
*/
typedef TBufC<KDbMaxColName> TDbColNameC;
/** Specifies when DBMS objects require a column ordinal to identify a column in
a column set or in a rowset.
Note that KDbNullColNo is a special value of TDbColNo used to indicate that
no such column exists.
@publishedAll
@released
*/
typedef TInt TDbColNo;
/**
Indicates that a specified column does not exist.
@publishedAll
@released
*/
const TDbColNo KDbNullColNo=0;
/**
A value returned by RDbRowSet::Count() when the number of rows cannot be determined.
@see RDbRowSet
@publishedAll
@released
*/
const TInt KDbUndefinedCount=-1;
/**
The length of a column is undefined.
@publishedAll
@released
*/
const TInt KDbUndefinedLength=-1;
/**
The default text column length. This is equal to 50.
@publishedAll
@released
*/
const TInt KDbDefaultTextColLength=50;
/**
Represents every supported column type.
@publishedAll
@released
*/
enum TDbColType
{
/** The column stores a single bit.
Representation range: 0 to 1
Storage: 1 bit
Auto-increment: Yes
Index key: Yes */
EDbColBit,
/** The column stores an 8-bit signed integer.
Representation range: -2^7 to 2^7 - 1
Storage: 1 byte
Auto-increment: Yes
Index key: Yes */
EDbColInt8,
/** The column stores an 8-bit unsigned integer.
Representation range: 0 to 2^8-1
Storage: 1 byte
Auto-increment: Yes
Index key: Yes */
EDbColUint8,
/** The column stores a 16-bit signed integer.
Representation range: -2^15 to 2^15 - 1
Storage: 2 bytes
Auto-increment: Yes
Index key: Yes */
EDbColInt16,
/** The column stores a 16-bit unsigned integer.
Representation range: 0 to 2^16-1
Storage: 2 bytes
Auto-increment: Yes
Index key: Yes */
EDbColUint16,
/** The column stores a 32-bit signed integer.
Representation range: -2^31 to 2^31 - 1
Storage: 4 bytes
Auto-increment: Yes
Index key: Yes */
EDbColInt32,
/** The column stores a 32-bit unsigned integer.
Representation range: 0 to 2^32-1
Storage: 4 bytes
Auto-increment: Yes
Index key: Yes */
EDbColUint32,
/** The column stores a 64-bit signed integer.
Representation range: -2^63 to 2^63 - 1
Storage: 8 bytes
Auto-increment: No
Index key: Yes */
EDbColInt64,
/** The column stores a 32-bit floating point value.
Representation range: 1.4 X 10^-45 to 3.40282 X 10^38
Storage: 4 bytes
Auto-increment: No
Index key: Yes */
EDbColReal32,
/** The column stores a 64-bit floating point value.
Representation range: 2.2 X 10^-308 to 1.79769 X 10^308
Storage: 8 bytes
Auto-increment: No
Index key: Yes */
EDbColReal64,
/** The column stores a date/time value.
Representation range: 1/1/0 to 31/12/9999
Storage: 8 bytes
Auto-increment: No
Index key: Yes */
EDbColDateTime,
/** The column stores a (short) variable length of non-Unicode text data.
Representation range: 0 to 256 characters
Storage: 0 to 256 bytes
Auto-increment: No
Index key: Yes */
EDbColText8,
/** The column stores a (short) variable length of Unicode text data.
Representation range: 0 to 256 characters
Storage: 0 to 512 bytes
Auto-increment: No
Index key: Yes */
EDbColText16,
/** The column stores a (short) variable length of untyped data.
Representation range: 0 to 255 bytes
Storage: 0 to 256 bytes
Auto-increment: No
Index key: No */
EDbColBinary,
/** The column stores a potentially large amount of non-Unicode text data.
Representation range: 0 to 2^31 characters
Storage: 0 to 2 Gbytes
Auto-increment: No
Index key: Truncated */
EDbColLongText8,
/** The column stores a potentially large amount of Unicode text data.
Representation range: 0 to 2^30 characters
Storage: 0 to 2 Gbytes
Auto-increment: No
Index key: Truncated */
EDbColLongText16,
/** The column stores a potentially large amount of untyped data.
Representation range: 0 to 2^31 bytes
Storage: 0 to 2 Gbytes
Auto-increment: No
Index key: No */
EDbColLongBinary,
/** This is equivalent to EDbColText8 if the build is narrow, and
EDbColText16 if the build is Unicode. */
EDbColText=EDbColText16,
/** This is equivalent to EDbColLongText8 if the build is narrow, and
EDbColLongText16 if the build is Unicode. */
EDbColLongText=EDbColLongText16
};
/**
Represents different ways of comparing Text and LongText columns.
This affects the ordering of indexes (see CDbKey), the evaluation of SQL
queries and matching row constraints (see TDbQuery).
@publishedAll
@released
*/
enum TDbTextComparison
{
/** Use standard text comparison and ordering. */
EDbCompareNormal,
/** Use folded text for comparison and ordering. */
EDbCompareFolded,
/** Use collation for comparison and ordering. */
EDbCompareCollated
};
/**
Defines a column in a table or rowset.
The data members are public because this is really a structure to group the
attributes of the column together.
Three non-default constructors are provided for convenience.
@publishedAll
@released
*/
class TDbCol
{
friend class CDbColSet;
public:
enum {ENotNull=0x01,EAutoIncrement=0x02};
public:
/** Constructs an uninitialised TDbCol. It is necessary because there are
also non-default constructors in this class. */
inline TDbCol() {}
inline TDbCol(const TDbCol&);
inline TDbCol& operator=(const TDbCol&);
IMPORT_C TDbCol(const TDesC& aName,TDbColType aType);
IMPORT_C TDbCol(const TDesC& aName,TDbColType aType,TInt aMaxLength);
static inline TBool IsLong(TDbColType aType);
private:
inline TDbCol(const TDesC& aName);
public:
/** The column type. */
TDbColType iType;
/** The maximum length of data that can be stored in a Text or Binary
column. */
TInt iMaxLength;
/** A set of flags describing other column attributes. This must be one
of the anonymous enum values ENotNull or EAutoIncrement. */
TUint iAttributes;
/** The column name. */
TDbColNameC iName;
};
/** Manages a set of column definitions which describe a table or rowset
structure. Column definitions can be added and removed. The set can be
iterated over, and ordinals for a column can be looked up.
The class is not intended for user derivation.
@publishedAll
@released
*/
class CDbColSet : public CBase
{
friend class TDbColSetIter;
public:
IMPORT_C CDbColSet();
IMPORT_C static CDbColSet* NewL();
IMPORT_C static CDbColSet* NewLC();
IMPORT_C ~CDbColSet();
inline const TDbCol& operator[](TDbColNo aCol) const;
IMPORT_C const TDbCol* Col(const TDesC& aColName) const;
IMPORT_C TDbColNo ColNo(const TDesC& aColName) const;
inline TInt Count() const;
inline void Clear();
IMPORT_C CDbColSet& AddL(const TDbCol& aCol);
IMPORT_C void Remove(const TDesC& aColName);
private:
CArrayPakFlat<TDbCol> iColumns;
};
/**
Provides a useful way to iterate over the contents of a column set.
@publishedAll
@released
*/
class TDbColSetIter
{
public:
IMPORT_C TDbColSetIter(const CDbColSet& aColSet);
inline operator TAny* () const;
inline const TDbCol& operator*() const;
inline const TDbCol* operator->() const;
IMPORT_C TDbColSetIter& operator++();
inline TDbColSetIter operator++(TInt);
inline TDbColNo Col() const;
private:
const TDbCol* iColumn;
TInt iIndex;
const CArrayPakFlat<TDbCol>* iArray;
};
/** Defines a key column in an index.
The data members are public as this is really a structure to group the
attributes of the key column together. Two non-default constructors are
provided for convenience.
@publishedAll
@released
*/
class TDbKeyCol
{
public:
/** Specifies whether a key column in an index should be sorted in
ascending or descending order. */
enum TOrder
{
/** Use ascending order. */
EAsc,
/** Use descending order. */
EDesc
};
public:
/** Constructs an uninitialised object. Default constructor. It is necessary
because there are also non-default constructors in this class. */
inline TDbKeyCol() {}
inline TDbKeyCol(const TDbKeyCol&);
inline TDbKeyCol& operator=(const TDbKeyCol&);
IMPORT_C TDbKeyCol(const TDesC& aName,TOrder anOrder=EAsc);
IMPORT_C TDbKeyCol(const TDesC& aName,TInt aLength,TOrder anOrder=EAsc);
public:
/** The ordering of the key. */
TOrder iOrder;
/** The maximum number of characters used to index Text or LongText
columns. If equal to KDbUndefinedLength (the default), all the characters
in the defined column will be used. */
TInt iLength;
/** The column name for the key. */
TDbColNameC iName;
};
/**
Represents the definition of an index. The key may be unique or primary, it
can specify the sort of comparison which is made for Text columns, and it
has a list of columns which make up the key. The class is used to construct
and interrogate index keys.
This class is not intended for user derivation.
@publishedAll
@released
*/
class CDbKey : public CBase
{
public:
enum {EUnique=0x01,EPrimary=0x02};
public:
IMPORT_C CDbKey();
IMPORT_C static CDbKey* NewL();
IMPORT_C static CDbKey* NewLC();
IMPORT_C ~CDbKey();
IMPORT_C CDbKey& AddL(const TDbKeyCol& aKeyCol);
IMPORT_C void Remove(const TDesC& aColName);
IMPORT_C void Clear();
inline TInt Count() const;
inline const TDbKeyCol& operator[](TInt aCol) const;
inline void MakeUnique();
inline TBool IsUnique() const;
inline void SetComparison(TDbTextComparison aComparison);
inline TDbTextComparison Comparison() const;
inline void MakePrimary();
inline TBool IsPrimary() const;
private:
CArrayPakFlat<TDbKeyCol> iKeys;
TDbTextComparison iComparison;
TInt iAttributes;
};
/**
Saves the current location of a rowset, enabling rapid navigation back to a
previously visited row or position in the set.
Instances of this class are returned by RDbRowSet::Bookmark(), which can later
be passed to RDbRowSet::GotoL() to return to the row which was current at
the call to Bookmark().
@see RDbRowSet::Bookmark()
@see RDbRowSet::GotoL()
@publishedAll
@released
*/
class TDbBookmark
{
friend class RDbRowSet;
public:
struct TMark
/** Stores a database bookmark. */
{
enum {ESize=8};
TUint32 iMark[ESize];
};
private:
TMark iMark;
};
/**
A wrapper for an SQL string combined with a text comparison mode.
An instance of the class is used as a parameter to RDbView::Prepare(),
RDbRowSet::FindL() and RDbRowConstraint::Open().
The evaluation of SQL queries or constraints depends on how Text columns are
compared so every SQL string is accompanied by a member of the TDbTextComparison
enumeration to indicate how comparison is done.
If the SQL string contains a LIKE clause with * (asterisks) wildcard then the
characters between them must be no longer than length 255.
If only one * exists then the length is taken from the start and to the end of
the clause. However, if the clause contains a ? (question mark) wildcard
within it then the characters between must be no longer than length 253.
@see TDbTextComparison
@see RDbView::Prepare()
@see RDbRowSet::FindL()
@see RDbRowConstraint::Open()
@publishedAll
@released
*/
class TDbQuery
{
public:
inline TDbQuery(const TDesC& aQuery,TDbTextComparison aComparison=EDbCompareNormal);
inline const TDesC& Query() const;
inline TDbTextComparison Comparison() const;
private:
const TDesC& iQuery;
TDbTextComparison iComparison;
};
/**
This class is internal and is not intended for use
@publishedAll
@released
*/
class RDbHandleBase
{
public:
inline RDbHandleBase();
void Close();
protected:
inline void Set(CDbObject* aObject);
CDbObject& Object() const;
protected:
CDbObject* iObject;
};
/**
This class is internal and is not intended for use.
@publishedAll
@released
*/
template <class T>
class RDbHandle : public RDbHandleBase
{
public:
inline T* operator=(T* aT);
inline T* operator->() const;
inline T& operator*() const;
inline T* operator()() const;
};
/**
Represents a pre-compiled SQL search-condition, which can be used to
test against the current row in a rowset.
The constraint is compiled against a specific rowset, and can only be matched
against the same rowset using the RDbRowSet::MatchL() function.
@see RDbRowSet
@publishedAll
@released
*/
class RDbRowConstraint
{
friend class RDbRowSet;
public:
IMPORT_C TInt Open(const RDbRowSet& aView,TDbQuery aCriteria);
IMPORT_C void Close();
private:
RDbHandle<CDbRowConstraint> iConstraint;
};
/**
An abstract base class that provides functionality which is shared between
SQL view objects and Table objects. This functionality includes most of the
cursor navigation, row retrieval and update behaviour of rowsets.
Rowset objects do not provide the data for the rowset on which they operate.
It is the responsibility of the derived classes RDbView and RDbTable to specify
the data source.
This class is not intended for user derivation.
@publishedAll
@released
*/
class RDbRowSet
{
friend class RDbRowConstraint;
friend class RDbColReadStream;
friend class RDbColWriteStream;
public:
/** Specifies where the rowset should navigate to in the GotoL() function.
Their use is encapsulated by the respective member functions FirstL(),
NextL() etc. */
enum TPosition
{
/** Move to the first row in the rowset. */
EFirst,
/** Move to the next row in the rowset. */
ENext,
/** Move to the previous row in the rowset. */
EPrevious,
/** Move to the last row in the rowset. */
ELast,
/** Move to the position before the first row in the rowset. */
EBeginning,
/** Move to the position after the last row in the rowset. */
EEnd
};
/** Specifies which operations can be performed on a rowset. */
enum TAccess
{
/** All operations can be performed on the rowset. */
EUpdatable,
/** Row navigation and reading are permitted. */
EReadOnly,
/** Inserting new rows is the only valid operation on the rowset. */
EInsertOnly
};
/** Specifies the direction to search through the rowset when using the
FindL() function. */
enum TDirection
{
/** Search from the current row forwards through the set. */
EForwards,
/** Search from the current row backwards through the set. */
EBackwards
};
/** Specifies whether the CountL() function should ensure that it returns
the exact value which may be a non-trivial task. */
enum TAccuracy
{
/** Take the time, if necessary, to return the exact value. */
EEnsure,
/** Return any immediately available value. */
EQuick
};
public:
IMPORT_C void Close();
IMPORT_C void Reset();
//
IMPORT_C CDbColSet* ColSetL() const;
IMPORT_C TInt ColCount() const;
IMPORT_C TDbColType ColType(TDbColNo aCol) const;
IMPORT_C TDbCol ColDef(TDbColNo aCol) const;
//
IMPORT_C TBool AtRow() const;
IMPORT_C TBool AtBeginning() const;
IMPORT_C TBool AtEnd() const;
//
IMPORT_C TInt CountL(TAccuracy anAccuracy=EEnsure) const;
IMPORT_C TBool IsEmptyL() const;
//
IMPORT_C TBool GotoL(TPosition aPosition);
inline void BeginningL();
inline void EndL();
inline TBool FirstL();
inline TBool LastL();
inline TBool NextL();
inline TBool PreviousL();
//
IMPORT_C TDbBookmark Bookmark() const;
IMPORT_C void GotoL(const TDbBookmark& aMark);
//
IMPORT_C TBool MatchL(const RDbRowConstraint& aConstraint);
IMPORT_C TInt FindL(TDirection aDirection,TDbQuery aCriteria);
//
IMPORT_C void GetL();
IMPORT_C void InsertL();
IMPORT_C void InsertCopyL();
IMPORT_C void UpdateL();
IMPORT_C void PutL();
IMPORT_C void Cancel();
IMPORT_C void DeleteL();
//
inline TBool IsColNull(TDbColNo aCol) const;
IMPORT_C TInt ColSize(TDbColNo aCol) const;
IMPORT_C TInt ColLength(TDbColNo aCol) const;
//
IMPORT_C TInt8 ColInt8(TDbColNo aCol) const;
IMPORT_C TInt16 ColInt16(TDbColNo aCol) const;
IMPORT_C TInt32 ColInt32(TDbColNo aCol) const;
IMPORT_C TInt64 ColInt64(TDbColNo aCol) const;
inline TInt ColInt(TDbColNo aCol) const;
IMPORT_C TUint8 ColUint8(TDbColNo aCol) const;
IMPORT_C TUint16 ColUint16(TDbColNo aCol) const;
IMPORT_C TUint32 ColUint32(TDbColNo aCol) const;
inline TUint ColUint(TDbColNo aCol) const;
IMPORT_C TReal32 ColReal32(TDbColNo aCol) const __SOFTFP;
IMPORT_C TReal64 ColReal64(TDbColNo aCol) const __SOFTFP;
inline TReal ColReal(TDbColNo aCol) const;
IMPORT_C TTime ColTime(TDbColNo aCol) const;
IMPORT_C TPtrC8 ColDes8(TDbColNo aCol) const;
IMPORT_C TPtrC16 ColDes16(TDbColNo aCol) const;
IMPORT_C TPtrC ColDes(TDbColNo aCol) const;
//
IMPORT_C void SetColNullL(TDbColNo aCol);
inline void SetColL(TDbColNo aCol,TInt aValue);
IMPORT_C void SetColL(TDbColNo aCol,TInt32 aValue);
IMPORT_C void SetColL(TDbColNo aCol,TInt64 aValue);
inline void SetColL(TDbColNo aCol,TUint aValue);
IMPORT_C void SetColL(TDbColNo aCol,TUint32 aValue);
IMPORT_C void SetColL(TDbColNo aCol,TReal32 aValue) __SOFTFP;
IMPORT_C void SetColL(TDbColNo aCol,TReal64 aValue) __SOFTFP;
IMPORT_C void SetColL(TDbColNo aCol,TTime aValue);
IMPORT_C void SetColL(TDbColNo aCol,const TDesC8& aValue);
IMPORT_C void SetColL(TDbColNo aCol,const TDesC16& aValue);
private:
inline MStreamBuf* ColSourceL(TDbColNo aCol) const;
inline MStreamBuf* ColSinkL(TDbColNo aCol);
CDbCursor& CheckCol(TDbColNo aCol) const;
TDbColumnC ColumnC(TDbColNo aCol,TDbColType aType) const;
TDbColumn Column(TDbColNo aCol,TDbColType aType);
protected:
RDbHandle<CDbCursor> iCursor;
};
/**
Allows any column value to be read as stream data.
Note that this is the only way to extract the contents of a Long column from
a rowset.
Only one column in a rowset object can be opened for reading as a stream at
a time, and while it is open no column in the same rowset object may be set
using RDbColWriteStream.
Null columns result in a read stream with no data. Small numeric columns are
maintained in memory as 32-bit values; hence reading a Uint8 column as a stream
results in 4 bytes of stream data, not 1.
@publishedAll
@released
*/
class RDbColReadStream : public RReadStream
{
public:
IMPORT_C void OpenL(const RDbRowSet& aView,TDbColNo aCol);
IMPORT_C void OpenLC(const RDbRowSet& aView,TDbColNo aCol);
};
/**
Writes Long columns when inserting or updating rows in a rowset.
Only one column in a rowset object can be opened for writing as a stream at
a time.
@publishedAll
@released
*/
class RDbColWriteStream : public RWriteStream
{
public:
/** Constructs this object by invoking the default constructor for
RWriteStream. */
inline RDbColWriteStream() {}
inline RDbColWriteStream(const MExternalizer<TStreamRef> &anExternalizer);
IMPORT_C void OpenL(RDbRowSet& aView,TDbColNo aCol);
IMPORT_C void OpenLC(RDbRowSet& aView,TDbColNo aCol);
};
/**
Describes the desired shape of a view's pre-evaluation window.
An instance of this class is passed to the RDbView object as part of the
Prepare() function. The different constructors for TDbWindow can specify a view:
without pre-evaluation
with full pre-evaluation
with limited pre-evaluation.
@see RDbView
@publishedAll
@released
*/
class TDbWindow
{
public:
/** Denotes a full pre-evaluation window. */
enum TUnlimited
{
/** No limit on how many rows may be in the window. */
EUnlimited=KMaxTInt
};
enum {ENone=0};
public:
inline TDbWindow();
inline TDbWindow(TUnlimited);
IMPORT_C TDbWindow(TInt aForeSlots,TInt aRearSlots);
inline TInt Size() const;
inline TInt PreferredPos() const;
private:
TInt iSize;
TInt iPreferredPos;
};
#if defined(__NO_CLASS_CONSTS__)
/**
@internalComponent
*/
#define KDbUnlimitedWindow TDbWindow(TDbWindow::EUnlimited)
#else
/**
@publishedAll
@released
*/
const TDbWindow KDbUnlimitedWindow=TDbWindow(TDbWindow::EUnlimited);
#endif
/**
Generates rowsets from an SQL query. The query is prepared and evaluated
using the interface to this class, while the rowset is manipulated using the
RDbRowset base class.
There are no special rules to consider when deriving from this class.
@publishedAll
@released
*/
class RDbView : public RDbRowSet
{
public:
IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,TAccess anAccess=EUpdatable);
IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow);
IMPORT_C TInt Prepare(RDbDatabase& aDatabase,const TDbQuery& aQuery,const TDbWindow& aWindow,TAccess anAccess);
IMPORT_C TInt EvaluateAll();
IMPORT_C TInt Evaluate();
IMPORT_C void Evaluate(TRequestStatus& aStatus);
IMPORT_C TBool Unevaluated() const;
};
/**
This class is internal and is not intended for use.
@publishedAll
@released
*/
template <class T>
class TUnion
{
public:
inline operator const T&() const;
inline const T& operator()() const;
inline T& operator()();
inline void Set(const T& aT);
private:
TUint8 iRep[sizeof(T)];
};
/**
This class is internal and is not intended for use.
@publishedAll
@released
*/
class TDbLookupKey
{
public:
struct SColumn
{
union
{
TInt32 iInt32;
TUint32 iUint32;
TUnion<TInt64> iInt64;
TReal32 iReal32;
TReal64 iReal64;
TUnion<TTime> iTime;
struct {const TText8* iPtr;TInt iLength;} iDes8;
struct {const TText16* iPtr;TInt iLength;} iDes16;
};
TDbColType iType;
};
public:
inline TDbLookupKey();
inline TInt Count() const;
inline const SColumn* First() const;
void Add(TInt aKey);
void Add(TUint aKey);
void Add(TInt64 aKey);
void Add(TReal32 aKey) __SOFTFP;
void Add(TReal64 aKey) __SOFTFP;
void Add(TTime aKey);
void Add(const TDesC8& aKey);
void Add(const TDesC16& aKey);
private:
SColumn& NextKey();
private:
TInt iCount;
SColumn iKey[1]; // at least one
};
/**
Database key value.
The class encapsulates a key value which is passed to RDbTable::SeekL(), for
lookup in the currently active index on that rowset.
An instance of this class can store a key value of any type.
Note that the class can only hold a single-column key. Use TDbSeekMultiKey
for multi-column keys.
@see TDbSeekMultiKey
@see RDbTable
@publishedAll
@released
*/
class TDbSeekKey
{
friend class RDbTable;
public:
inline TDbSeekKey();
inline TDbSeekKey(TInt aKey);
inline TDbSeekKey(TUint aKey);
inline TDbSeekKey(TInt64 aKey);
inline TDbSeekKey(TReal32 aKey);
inline TDbSeekKey(TReal64 aKey);
inline TDbSeekKey(TTime aKey);
inline TDbSeekKey(const TDesC8& aKey);
inline TDbSeekKey(const TDesC16& aKey);
IMPORT_C TDbSeekKey& Add(TInt aKey);
IMPORT_C TDbSeekKey& Add(TUint aKey);
IMPORT_C TDbSeekKey& Add(TInt64 aKey);
IMPORT_C TDbSeekKey& Add(TReal32 aKey) __SOFTFP;
IMPORT_C TDbSeekKey& Add(TReal64 aKey) __SOFTFP;
IMPORT_C TDbSeekKey& Add(TTime aKey);
IMPORT_C TDbSeekKey& Add(const TDesC8& aKey);
IMPORT_C TDbSeekKey& Add(const TDesC16& aKey);
private:
TDbLookupKey& Check();
protected:
inline TDbSeekKey(TInt aKeys,TInt);
private:
TInt iMaxKeys;
TDbLookupKey iKey;
};
/**
Database multi-column key value.
The class extends the behaviour of TDbSeekKey by allowing multi-column indexes
to be searched using multi-column key values.
The template parameter S specifies the maximum number of column values that
can be added to the key value.
Use the TDbSeekKey::Add() members to append the values for each column in
the key value.
@publishedAll
@released
*/
template<TInt S>
class TDbSeekMultiKey : public TDbSeekKey
{
public:
inline TDbSeekMultiKey();
private:
TDbLookupKey::SColumn iExtraKeys[S-1];
};
/**
Provides access to table data as a rowset, allowing manipulation of a named
table in the database. Additionally, a named index can be used to order the
rowset, and to provide fast key-based row retrieval from the table.
There are no special rules to consider when deriving from this class.
@publishedAll
@released
*/
class RDbTable : public RDbRowSet
{
public:
/** Database table seek comparison types. */
enum TComparison
{
/** Retrieve the last row which is strictly less than the key value. */
ELessThan,
/** Retrieve the last row which is equal to or less than the key
value. */
ELessEqual,
/** Retrieve the first row which is equal to the key value. */
EEqualTo,
/** Retrieve the first row which is equal to or greater than the key
value. */
EGreaterEqual,
/** Retrieve the first row which is strictly greater than the key
value. */
EGreaterThan
};
public:
IMPORT_C TInt Open(RDbDatabase& aDatabase,const TDesC& aName,TAccess anAccess=EUpdatable);
inline TInt SetIndex(const TDesC& anIndex);
inline TInt SetNoIndex();
IMPORT_C TBool SeekL(const TDbSeekKey& aKey,TComparison aComparison=EEqualTo);
private:
IMPORT_C TInt SetIndex(const TDesC* anIndex);
};
/**
@publishedAll
@released
*/
class CDbNames : public CBase
{
private:
inline CDbNames();
public:
static CDbNames* NewLC();
~CDbNames();
inline TInt Count() const;
inline const TDesC& operator[](TInt anIndex) const;
IMPORT_C void AddL(const TDesC& aName);
private:
CArrayPakFlat<TDbNameC> iList;
};
/**
@publishedAll
@released
*/
typedef CDbNames CDbTableNames,CDbIndexNames,CDbDatabaseNames;
/**
The maximum length for a generic DBMS string, which might be transferred from DBMS server
to the DBMS client using IPC.
@publishedAll
@released
*/
const TInt KDbMaxStrLen = 256;
/**
Represents a generic read-only DBMS string. It maps to a non-modifiable buffer descriptor
with maximum size KDbMaxStrLen.
@see TBufC
@publishedAll
@released
*/
typedef TBufC<KDbMaxStrLen> TDbStringC;
/**
CDbStrings encapsulates functionality used for transferring an array of strings from
DBMS server to the DBMS client. The maximal length of each element of the array is
KDbMaxStrLen characters.
The typical usage pattern of CDbStrings class is:
@code
CDbStrings* strings = <a call of an exported DBMS method>;
TInt cnt = strings.Count();
for(TInt i=0;i<cnt;++i)
{
const TDesC& str = (*strings)[i];
<do something with "str" variable>;
}
delete strings;
@endcode
@publishedAll
@released
*/
class CDbStrings : public CBase
{
private:
inline CDbStrings();
public:
static CDbStrings* NewLC();
virtual ~CDbStrings();
inline TInt Count() const;
inline const TDesC& operator[](TInt aIndex) const;
void AddL(const TDesC& aStr);
private:
CArrayPakFlat<TDbStringC> iList;
};
/**
Abstract class providing the functionality of a database.
The source of the database and the implementation characteristics of a particular
database are provided by a class derived from RDbDatabase.
DBMS has one such implementation: the store database.
This class is not intended for user derivation.
Note: For functions (i.e. Execute) that take an Sql string, if the string
contains a LIKE clause with * (asterisks) wildcard then the
characters between them must be no longer than length 255.
If only one * exists then the length is taken from the start and to the end of
the clause. However, if the clause contains a ? (question mark) wildcard
within it then the characters between must be no longer than length 253.
@publishedAll
@released
*/
class RDbDatabase
{
friend class RDbView;
friend class RDbTable;
friend class RDbIncremental;
friend class RDbUpdate;
friend class RDbNotifier;
public:
struct TSize {TInt iSize;TInt iUsage;};
public:
IMPORT_C void Close();
IMPORT_C TInt Destroy();
//
IMPORT_C TBool IsDamaged() const;
IMPORT_C TInt Recover();
//
IMPORT_C TInt UpdateStats();
IMPORT_C TSize Size() const;
IMPORT_C TInt Compact();
IMPORT_C TInt Begin();
IMPORT_C TInt Commit();
IMPORT_C void Rollback();
IMPORT_C TBool InTransaction() const;
//
inline TInt CreateTable(const TDesC& aName,const CDbColSet& aDef);
inline TInt CreateTable(const TDesC& aName,const CDbColSet& aDef,const CDbKey& aPrimaryKey);
IMPORT_C TInt DropTable(const TDesC& aName);
IMPORT_C TInt AlterTable(const TDesC& aName,const CDbColSet& aNewDef);
IMPORT_C TInt CreateIndex(const TDesC& aName,const TDesC& aTable,const CDbKey& aKey);
IMPORT_C TInt DropIndex(const TDesC& aName,const TDesC& aTable);
//
IMPORT_C TInt Execute(const TDesC& aSql,TDbTextComparison aComparison=EDbCompareNormal);
//
IMPORT_C CDbTableNames* TableNamesL() const;
IMPORT_C CDbColSet* ColSetL(const TDesC& aName) const;
IMPORT_C CDbIndexNames* IndexNamesL(const TDesC& aTable) const;
IMPORT_C CDbKey* KeyL(const TDesC& aName,const TDesC& aTable) const;
private:
IMPORT_C TInt CreateTable(const TDesC& aName,const CDbColSet& aColSet,const CDbKey* aPrimaryKey);
protected:
RDbHandle<CDbDatabase> iDatabase;
};
/**
Provides the interface for performing long-running database operations in
incremental steps, allowing application programs to remain responsive to other
events.
After an operation has begun, a standard interface is used to continue and
complete all incremental operations. On successful return from one of the
initiating functions, a step value is also returned. This gives the progress
indication and is, initially, positive. This value should be passed into
subsequent steps in the operation, each of which may decrement the value by
some amount, although they are allowed to leave it unchanged. The value
reaches zero, if, and only if the operation completes.
While an incremental operation is in progress, the database cannot be used
for any other operations such as opening tables or preparing views.
Starting an incremental operation also requires that no rowsets are open on
the database and that no commit is pending for data manipulation transactions.
If no explicit transaction has been started by the database, then an automatic
transaction is begun when any incremental operation is started and is committed
when complete or rolled back if the operation either fails or is abandoned
prior to completion.
@publishedAll
@released
*/
class RDbIncremental
{
public:
IMPORT_C void Close();
IMPORT_C TInt Next(TInt& aStep);
IMPORT_C void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);
//
IMPORT_C TInt Recover(RDbDatabase& aDatabase,TInt& aStep);
IMPORT_C TInt Compact(RDbDatabase& aDatabase,TInt& aStep);
IMPORT_C TInt DropTable(RDbDatabase& aDatabase,const TDesC& aTable,TInt& aStep);
IMPORT_C TInt AlterTable(RDbDatabase& aDatabase,const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep);
IMPORT_C TInt CreateIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,const CDbKey& aKey,TInt& aStep);
IMPORT_C TInt DropIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,TInt& aStep);
inline TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TInt& aStep);
IMPORT_C TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep);
IMPORT_C TInt UpdateStats(RDbDatabase& aDatabase,TInt& aStep);
private:
RDbHandle<CDbIncremental> iState;
};
/**
Provides an interface to allow incremental execution of a DML (SQL data
update) statement.
This class offers similar behaviour to the RDbIncremental class, in that it
allows an application to perform long running operations while remaining
responsive to events. However, unlike that class, RDbUpdate is restricted to
executing DML statements.
@see RDbIncremental
@publishedAll
@released
*/
class RDbUpdate
{
public:
IMPORT_C TInt Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison=EDbCompareNormal);
IMPORT_C void Close();
//
IMPORT_C TInt Next();
IMPORT_C void Next(TRequestStatus& aStatus);
IMPORT_C TInt RowCount() const;
private:
RDbHandle<CDbIncremental> iUpdate;
TPckgBuf<TInt> iRows;
};
/**
Provides notification of database changes to clients.
This is useful for shared databases.
@publishedAll
@released
*/
class RDbNotifier
{
public:
/** Defines the events which may be reported by a DBMS change notifier
through this RDbNotifier object.
Each enumerator corresponds to a distinct event type.
The changes are reported through a TRequestStatus object when an
outstanding notification request completes.
Notes
If further database events occur while a client is handling the completion
of a previous event, the notifier remembers the most significant event. The
order of importance is:
ERecover > ERollback > ECommit
where the symbol > means "is more important than" */
enum TEvent
{
/** The database has been closed. */
EClose,
/** All read locks have been removed. */
EUnlock,
/** A transaction has been committed. */
ECommit,
/** A transaction has been rolled back */
ERollback,
/** The database has been recovered */
ERecover
};
public:
IMPORT_C TInt Open(RDbDatabase& aDatabase);
IMPORT_C void Close();
//
IMPORT_C void NotifyUnlock(TRequestStatus& aStatus);
IMPORT_C void NotifyChange(TRequestStatus& aStatus);
IMPORT_C void Cancel();
private:
RDbHandle<CDbNotifier> iNotifier;
};
/**
Client-server databases
Represents a session with the DBMS server. A thread uses this class to set
up a DBMS server session and this provides the basis for sharing databases
with other threads.
@publishedAll
@released
*/
class RDbs : public RSessionBase
{
public:
/**
This enum is used in GetDatabasePolicy/GetTablePolicy/GetTablePolicies calls and specifies
requested security policy type: read/write/schema.
@publishedAll
@released
*/
typedef enum {EReadPolicy, EWritePolicy, ESchemaPolicy} TPolicyType;
public:
IMPORT_C static TVersion Version();
IMPORT_C TInt Connect();
IMPORT_C CDbDatabaseNames* DatabaseNamesL(TDriveNumber aDrive, TUid aPolicyUid);
IMPORT_C TInt CopyDatabase(const TDesC& aSrcDbName, const TDesC& aDestDbName, TUid aPolicyUid);
IMPORT_C TInt DeleteDatabase(const TDesC& aDbName, TUid aPolicyUid);
IMPORT_C TInt GetDatabasePolicy(TUid aPolicyUid, TPolicyType aPolicyType,
TSecurityPolicy& aDbPolicy);
IMPORT_C TInt GetTablePolicy(TUid aPolicyUid, const TDesC& aTableName,
TPolicyType aPolicyType, TSecurityPolicy& aTablePolicy);
IMPORT_C TInt GetTablePolicies(TUid aPolicyUid, const TDesC& aTableName,
TPolicyType aPolicyType,
TSecurityPolicy& aDbPolicy, TSecurityPolicy& aTablePolicy);
//
IMPORT_C void ResourceMark();
IMPORT_C void ResourceCheck();
IMPORT_C TInt ResourceCount();
IMPORT_C void SetHeapFailure(TInt aTAllocFail,TInt aRate);
IMPORT_C TInt ReserveDriveSpace(TInt aDriveNo, TInt aSpace);
IMPORT_C void FreeReservedSpace(TInt aDriveNo);
IMPORT_C TInt GetReserveAccess(TInt aDriveNo);
IMPORT_C TInt ReleaseReserveAccess(TInt aDriveNo);
IMPORT_C TInt GetBackupPath(TSecureId aRequesterSid, const TDesC& aDbName,
TUid aDbPolicyUid, TDes& aBackupPath);
IMPORT_C CDbStrings* BackupPathsL(TSecureId aRequesterSid, TUid aDbPolicyUid);
private:
TInt DoConnect();
TInt SessionMessage(TInt aFunction);
TInt GetPolicy(TUid aPolicyUid, const TDesC& aTableName,
TUint aMask, TSecurityPolicy& aPolicy);
};
/**
Generic database implementation
@publishedAll
@released
*/
class RDbNamedDatabase : public RDbDatabase
{
public:
/** Specifies which operations can be performed on a rowset. */
enum TAccess
{
EReadWrite,
/** Row navigation and reading are permitted. */
EReadOnly
};
public:
IMPORT_C TInt Create(RDbs& aDbs, const TDesC& aDatabase, const TDesC& aFormat);
IMPORT_C TInt Create(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
IMPORT_C TInt Replace(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
IMPORT_C TInt Open(RFs& aFs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC(),TAccess aMode=EReadWrite);
IMPORT_C TInt Open(RDbs& aDbs,const TDesC& aDatabase,const TDesC& aFormat=TPtrC());
};
/**
@internalComponent
*/
const TInt KDbStoreMaxColumnLength=255;
/**
DBMS Store database implementation
@publishedAll
@released
*/
class RDbStoreDatabase : public RDbDatabase
{
public:
IMPORT_C TStreamId CreateL(CStreamStore* aStore);
IMPORT_C void OpenL(CStreamStore* aStore,TStreamId anId);
IMPORT_C static void CompressL(CStreamStore& aStore,TStreamId aId);
IMPORT_C static void DecompressL(CStreamStore& aStore,TStreamId aId);
};
#include <d32dbms.inl>
#endif