CBookDb Class Reference

List of all members.

Public Member Functions
	~CBookDb ()
TInt	OpenDb (const TFileName &aExistingBookFile)
TInt	CreateDb (const TFileName &aNewBookFile)
TInt	RemoveDb (const TFileName &aExistingBookFile)
TInt	Close ()
TBool	IsOpen () const
TInt	AddBookWithSql (const TDesC &aAuthor, const TDesC &aTitle, const TDesC &aDescription)
TInt	AddBookWithCppApiL (const TDesC &aAuthor, const TDesC &aTitle, const TDesC &aDescription)
CDesCArrayFlat *	GetAllBooksL ()
CDesCArrayFlat *	GetBooksByKeyL (const TDesC &aColumnName, const TDesC &aSearchString)
TInt	GetABookFast (const TDesC &aTitle, TDes &aResult)
TInt	RemoveBooks (const TDesC &aTitle, TInt &aResultCount)
TInt	RemoveAllBooks (TInt &aResultCount)
TInt	UpdateBookTitle (const TDesC &aOldTitleKey, const TDesC &aNewTitle)
CDesCArrayFlat *	ColumnNamesAndSizesL ()
TInt	HasDateColumn (TBool &aReturnValue)
TInt	AddDateColumn ()
TInt	RemoveDateColumn ()
Static Public Member Functions
static CBookDb *	NewL ()

---

Detailed Description

Class: CBookDb

Description: An instance of class CBookDb provides simple Book database access: creating & manipulating Book database files and database entries (books).

Database definition:

The Book contains one table as follows:

Table name: Books Column: Type: Max length: ------ ----- ----------- Author EDbColText 50 (using default) Title EDbColText 60 (see KTitleMaxLength) Description EDbColLongText 128 (see KDescriptionMaxLength) In run time: PublishDate EDbColDateTime

Note that underlying database allows description to be up to 2GB long, but this engine limits the size to 128 unicode characters. The PublishDate does not exist, when the database is created. It can be added on the fly (see AddDateColumnL method).

There is also index for Books table with name "BooksIndex". It consists of two columns:

Author, Title

Index provides quick find.

Definition at line 74 of file DBMSEngine.h.

---

Constructor & Destructor Documentation

CBookDb::~CBookDb

(

)

Function: ~CBookDb

Description: Destroy the object.

Definition at line 34 of file DBMSEngine.cpp.

---

Member Function Documentation

CBookDb * CBookDb::NewL

(

)

[static]

Function: NewL

Description: Get instance of a CBookDb object.

Definition at line 20 of file DBMSEngine.cpp.

TInt CBookDb::OpenDb

(

const TFileName &

aExistingBookFile

)

Function: OpenDbL

Description: Open existing Book database in exclusive (non-shared) mode.

Param: aExistingBookFile is full path to Book database file.

Return: KErrNone, if no error. KErrNotFound, if the file does not exist.

Leaves: With one of the system wide error codes, if the file is not a correct database file.

Definition at line 67 of file DBMSEngine.cpp.

TInt CBookDb::CreateDb

(

const TFileName &

aNewBookFile

)

Function: CreateDbL

Description: Creates and opens a new Book database. Creates a database file, table structure and an index. The database will be open in exclusive (non-shareable) mode. The database must be closed, when not used any more. If the database exists, it is replaced.

Param: aNewBookFile Name of the new database file. Is a full path (incl. the filename). Operations following this call are performed to the new database file.

Return: returns always KErrNone

Leaves: If the file cannot be created or database initialized. Leaves with system wide error codes.

Definition at line 96 of file DBMSEngine.cpp.

TInt CBookDb::RemoveDb

(

const TFileName &

aExistingBookFile

)

Function: RemoveDbL

Description: Removes Book database. Closes any open database, before dropping the database.

Param: aExistingBookFile is full path to Book database file.

Leaves: If the file file is not a valid database file or the database does not containt Books table, the method leaves with system wide error codes.

Definition at line 126 of file DBMSEngine.cpp.

TInt CBookDb::Close

(

)

Function: Close

Description: Closes the database opened with either OpenDbL or CreateDbL. It is safe to close the database even if it is closed.

Return: KErrNone, if no error. KErrNotFound, if the file does not exist.

Definition at line 156 of file DBMSEngine.cpp.

TBool CBookDb::IsOpen

(

)

const

Function: IsOpen

Description: Return status, whether the database is open and ready for operations.

Definition at line 173 of file DBMSEngine.cpp.

TInt CBookDb::AddBookWithSql	(	const TDesC &	aAuthor,
		const TDesC &	aTitle,
		const TDesC &	aDescription
	)

Function: AddBookWithSql

Description: Adds a new book to Books table. The book is inserted using SQL and RDbView.

Param: aAuthor Author of the book. Must be shorter than the default max text length in Book API (=50). Must not be empty.

Param: aTitle Title of the book. Must be shorter than KTitleMaxLength. Must not be empty.

Param: aDescription Description of the book. It must not be longer than KDescriptionMaxLength. Must not be empty.

Definition at line 254 of file DBMSEngine.cpp.

TInt CBookDb::AddBookWithCppApiL	(	const TDesC &	aAuthor,
		const TDesC &	aTitle,
		const TDesC &	aDescription
	)

Function: AddBookWithCppApiL

Description: Adds a new book to Books table. The book is inserted using RDbTable API.

Param: aAuthor Author of the book. Must be shorter than the default max text length in Book API (=50). Must not be empty.

Param: aTitle Title of the book. Must be shorter than KTitleMaxLength. Must not be empty.

Param: aDescription Description of the book. It must not be longer than KDescriptionMaxLength. Must not be empty.

Definition at line 326 of file DBMSEngine.cpp.

CDesCArrayFlat * CBookDb::GetAllBooksL

(

)

Function: GetAllBooksL

Description: Retrieve all books from database.

Returns: Array of books. Each array item is represented as follows: <Author>|<Title>| Maximum length of each item is KBookItemMaxLength Caller takes ownership of the array.

Definition at line 385 of file DBMSEngine.cpp.

CDesCArrayFlat * CBookDb::GetBooksByKeyL	(	const TDesC &	aColumnName,
		const TDesC &	aSearchString
	)

Function: GetBooksByKeyL

Description: Retrieve books from database, which match given column and search pattern. Implementation uses SQL.

Param: aColumnName Name of the column to apply the search pattern. Must be either KBooksAuthorCol or KBooksTitleCol

Param: aSearchString Search pattern used to restrict results to.

Returns: Array of books. Each array item is represented as follows: <Author>|<Title>| Maximum length of each item is KBookItemMaxLength Caller takes ownership of the array.

Definition at line 515 of file DBMSEngine.cpp.

TInt CBookDb::GetABookFast	(	const TDesC &	aTitle,
		TDes &	aResult
	)

Function: GetABookFast

Description: Retrieves book information for given book name. This method uses index to find first occurrence of the book. Implementation uses exact match.

Param: aTitle is name of the book to search for.

Param: aResult If there is a matching book, the complete book info is written to aResult. It is in the following format: <Author>|<Title>| Length of the given descriptor must be KBookItemMaxLength

Definition at line 441 of file DBMSEngine.cpp.

TInt CBookDb::RemoveBooks	(	const TDesC &	aTitle,
		TInt &	aResultCount
	)

Function: RemoveBooks

Description: Deletes book(s) from database.

Param: aTitle is name of the book to delete. It can contain wildcard characters (% for single char, * for zero or multiple chars).

Param: aResultCount will contain number of deleted books.

Returns: KErrNone or one of the system wide error codes.

Definition at line 604 of file DBMSEngine.cpp.

TInt CBookDb::RemoveAllBooks

(

TInt &

aResultCount

)

Function: RemoveAllBooksL

Description: Deletes all books from database.

Param: aResultCount will contain number of deleted books.

Returns: KErrNone or one of the system wide error codes.

Definition at line 646 of file DBMSEngine.cpp.

TInt CBookDb::UpdateBookTitle	(	const TDesC &	aOldTitleKey,
		const TDesC &	aNewTitle
	)

Function: UpdateBookTitle

Description: Changes the title for a book (or books, if there are multiple books with the name aOldTitleKey).

Param: aOldTitleKey Book title used for getting books for update.

Param: aNewTitle New title for the book(s).

Returns: KErrNone or one of the system wide error codes.

Definition at line 681 of file DBMSEngine.cpp.

CDesCArrayFlat * CBookDb::ColumnNamesAndSizesL

(

)

Function: ColumnNamesAndSizes

Description: Get array of colum names in the Books table. The result array includes also the size of the textual columns. This is here just to demonstrate iterating column names from a table.

Returns: Array of column names. Caller takes ownership.

Definition at line 704 of file DBMSEngine.cpp.

TInt CBookDb::HasDateColumn

(

TBool &

aReturnValue

)

Function: HasDateColumn

Description: Tests whether the Books table has date column.

Returns: KErrNone or one of the system wide error codes.

Definition at line 754 of file DBMSEngine.cpp.

TInt CBookDb::AddDateColumn

(

)

Function: AddDateColumn

Description: Adds date column to Books table. This here just to demonstrate how to alter table definition. This fails, if the date column already exists.

Returns: KErrNone or one of the system wide error codes.

Definition at line 794 of file DBMSEngine.cpp.

TInt CBookDb::RemoveDateColumn

(

)

Function: RemoveDateColumn

Description: Removes date column from Books table. This here just to demonstrate how to alter table definition. This fails, if the date column does not exist.

Returns: KErrNone or one of the system wide error codes.

Definition at line 805 of file DBMSEngine.cpp.