Collapse all Symbian^3 Product Developer Library

CCommsDbTemplateRecord Class Reference

class CCommsDbTemplateRecord : public CBase

The view on a template record of a specific table.

The view contains only the template record and therefore, unlike the more general CCommsDbTableView class, does not contain any navigation functions.

This class does, however, contain the necessary member functions for reading and writing to columns.

Inherits from

CCommsDbTemplateRecord
- CBase

Public Member Functions
	~CCommsDbTemplateRecord()
IMPORT_C void	CancelModifications()
IMPORT_C TInt	Delete()
IMPORT_C void	GetTableName(TDes &)
IMPORT_C TInt	InsertCopy(TUint32 &)
IMPORT_C TInt	Modify()
IMPORT_C CCommsDbTemplateRecord *	NewL(CCommsDatabaseBase *, const TDesC &)
IMPORT_C void	ReadBoolL(const TDesC &, TBool &)
IMPORT_C void	ReadColumnLengthL(const TDesC &, TInt &)
IMPORT_C HBufC *	ReadLongTextLC(const TDesC &)
IMPORT_C void	ReadTextL(const TDesC &, TDes8 &)
IMPORT_C void	ReadTextL(const TDesC &, TDes16 &)
IMPORT_C void	ReadTypeAttribL(const TDesC &, TDbColType &, TUint32 &)
IMPORT_C void	ReadUintL(const TDesC &, TUint32 &)
IMPORT_C TInt	StoreModifications()
IMPORT_C TBool	TemplateRecordExists()
IMPORT_C void	WriteBoolL(const TDesC &, const TBool &)
IMPORT_C void	WriteLongTextL(const TDesC &, const TDesC &)
IMPORT_C void	WriteTextL(const TDesC &, const TDesC8 &)
IMPORT_C void	WriteTextL(const TDesC &, const TDesC16 &)
IMPORT_C void	WriteUintL(const TDesC &, const TUint32 &)

Private Member Functions
	CCommsDbTemplateRecord()
void	ClearHiddenMask(TBool)
void	ConstructL(CCommsDatabaseBase *, const TDesC &)
TInt	Reposition()
TBool	SetHiddenMask()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
TBool	iRecordExists
CCommsDbTableView *	iView

Constructor & Destructor Documentation

CCommsDbTemplateRecord()

CCommsDbTemplateRecord

(

)

[private]

Default Constructor

~CCommsDbTemplateRecord()

IMPORT_C

~CCommsDbTemplateRecord

(

)

Frees all resources owned by this object, prior to its destruction. Specifically, it closes the view.

Member Functions Documentation

CancelModifications()

IMPORT_C void

CancelModifications

(

)

Cancels pending changes since `Modify()`.

Abandons changes made to the template record which were started by a call to Modify().

A call to Modify() must have previously been made otherwise the function raises a CommsDbServer 5 panic.

ClearHiddenMask(TBool)

void

ClearHiddenMask

(

TBool

aClearHiddenMask

)

[private]

Parameters

TBool aClearHiddenMask

ConstructL(CCommsDatabaseBase *, const TDesC &)

void	ConstructL	(	CCommsDatabaseBase *	aDb,
			const TDesC &	aTableName
		)	[private]

Parameters

CCommsDatabaseBase * aDb
const TDesC & aTableName

Delete()

IMPORT_C TInt

Delete

(

)

Removes the template from the table.

Deletes the template record.

This function raises a CommsDbServer 3 panic if a previous call to Modify() has been made.

capability: Dependent on table, see the guide page referenced below.

GetTableName(TDes &)

IMPORT_C void

GetTableName

(

TDes &

aTableName

)

const

The name of the table that this template belongs to.

Gets the name of the table associated with this view and copy it into the descriptor supplied by the caller.

Parameters

TDes & aTableName

A reference to a descriptor passed by the caller. On return from this function it contains the name of the table.

InsertCopy(TUint32 &)

IMPORT_C TInt

InsertCopy

(

TUint32 &

aId

)

Creates a new record based on the contents of the template record

capability: Dependent on table, see the guide page referenced below.

Parameters

TUint32 & aId

On return contains the unique Id associated with this new record.

Modify()

IMPORT_C TInt

Modify

(

)

Modifies the existing template record if there is no template create one. StoreModifications() is called to complete the transaction.

Prepares to update the template record, if it exists. If the template record does not exist, it is created and left ready for modification. The function must be called before writing to any column. Once all changes to the template record are complete, a call must be made to either StoreModifications() or CancelModifications() as appropriate.

From v9.1 template record always exist

This function raises a CommsDbServer 1 or a CommsDbServer 2 panic if a previous call to Modify() has already been made.

This function must be called before any attempt is made to write to a column otherwise subsequent write operations raise a CommsDbServer 12 panic.

Once this function has completed successfully, no attempt can be made to read from a column until either StoreModifications() or CancelModifications() has been called to complete the record insertion operation, otherwise the read operations raise a CommsDbServer 10 panic.

NewL(CCommsDatabaseBase *, const TDesC &)

IMPORT_C CCommsDbTemplateRecord *	NewL	(	CCommsDatabaseBase *	aDb,
			const TDesC &	aTableName
		)	[static]

Creates a new template view on the database and table specified.

Allocates and constructs a view, which includes only the template record, on the table whose name is defined in the specified descriptor and which is in the specified communications database.

The view is restricted to the single template record in the table.

The communications database, pointed to by aDb should already have been opened.

Parameters

CCommsDatabaseBase * aDb	A pointer to the communications database object. This pointer must not be NULL.
const TDesC & aTableName	A reference to a descriptor containing the name of a table in the communications database.

ReadBoolL(const TDesC &, TBool &)

IMPORT_C void	ReadBoolL	(	const TDesC &	aColumn,
			TBool &	aValue
		)

Reads a boolean value located in a specific column within the template record and copies it into the specified descriptor. The column is identified by the name supplied in the descriptor aColumn.

This read operation must not occur if any of the operations involved in changing the template record are still outstanding, otherwise the function raises a CommsDbServer 10 panic. For example, the panic is raised if this function is called between calls to Modify() and StoreModifications().

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

If the template record does not exist then the function leaves with KErrUnknown.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of the column in the template record whose (boolean) value is to be read.
TBool & aValue	A reference to a TBool passed by the caller.

ReadColumnLengthL(const TDesC &, TInt &)

IMPORT_C void	ReadColumnLengthL	(	const TDesC &	aColumn,
			TInt &	aLength
		)

Gets the length of a specific column within the template record and copies it to an integer passed by the caller. The column is identified by the name supplied in the descriptor aColumn.

This read operation must not occur if any of the operations involved in changing a template record are still outstanding, otherwise the function raises a CommsDbServer 10 panic. For example, the panic is raised if this function is called between calls to Modify() and StoreModifications().

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

If the template record does not exist, this function will just return with aLength set to zero.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the template record.
TInt & aLength	A reference to an integer passed by the caller. On successful return from this function, contains a copy of the length of the column.

ReadLongTextLC(const TDesC &)

IMPORT_C HBufC *

ReadLongTextLC

(

const TDesC &

aColumn

)

Reads the long text located in a specific column within the template record and copies this text to a heap descriptor. The heap descriptor is allocated and its pointer returned by this function. The column is identified by the name supplied in the descriptor aColumn.

While the text in columns retrieved by the ReadTextL() functions is limited in length, there is no restriction on the length of long text.

If the template record does not exist, this function will just return an empty desciptor. Also in this case, the caller is still responsible for removing this object from the cleanup stack.

This read operation must not occur if any of the operations involved in changing a record are still outstanding, otherwise the function raises a CommsDbServer 10 panic. For example, the panic is raised if this function is called between calls to Modify() and StoreModifications().

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn

A reference to a descriptor containing the name of a column in the template record.

ReadTextL(const TDesC &, TDes8 &)

IMPORT_C void	ReadTextL	(	const TDesC &	aColumn,
			TDes8 &	aValue
		)

Reads narrow (ASCII) text located in a specific column within the template record and copies it to the specified 8 bit modifiable descriptor. The column is identified by the name supplied in the descriptor aColumn.

The maximum length of text expected by this function is the value of the constant KCommsDbSvrMaxColumnNameLength. The maximum length of aValue supplied by the caller can, therefore, be the same.

If the template record does not exist, this function will just return with an empty aValue desciptor.

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of the column in the template record whose (narrow text) value is to be read.
TDes8 & aValue	A reference to an 8 bit descriptor passed by the caller.

ReadTextL(const TDesC &, TDes16 &)

IMPORT_C void	ReadTextL	(	const TDesC &	aColumn,
			TDes16 &	aValue
		)

Reads wide (UNICODE) text located in a specific column within the template record and copies it to the specified 16 bit modifiable descriptor. The column is identified by the name supplied in the descriptor aColumn.

The maximum length of text expected by this function is the value of the constant KCommsDbSvrMaxColumnNameLength. The maximum length of aValue supplied by the caller can, therefore, be the same.

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

If the template record does not exist, this function will just return with an empty aValue desciptor.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of the column in the template record whose (wide text) value is to be read.
TDes16 & aValue	A reference to a 16 bit descriptor passed by the caller.

ReadTypeAttribL(const TDesC &, TDbColType &, TUint32 &)

IMPORT_C void	ReadTypeAttribL	(	const TDesC &	aColumn,
			TDbColType &	aColType,
			TUint32 &	aAttrib
		)

Gets the type and the attributes of a specific column within the template record and puts them into a reference to an object and a reference to an unsigned integer respectively. The column is identified by the name supplied in the descriptor aColumn.

The column type is described by the TDbColType enumerator.

The column attributes are one or more of the values TDbCol::ENotNull and TDbCol::EAutoIncrement.

This function must not be called if any of the operations involved in changing the template record are still outstanding, otherwise the function raises a CommsDbServer 10 panic. For example, the panic is raised if this function is called between calls to Modify() and StoreModifications().

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of the column in the template record whose type and attributes are to be fetched.
TDbColType & aColType	A reference to a TDbColType object passed by the caller. On successful return from this function, contains a copy of the column type.
TUint32 & aAttrib	A reference to an unsigned integer passed by the caller. On successful return from this function, contains a copy of the column attributes.

ReadUintL(const TDesC &, TUint32 &)

IMPORT_C void	ReadUintL	(	const TDesC &	aColumn,
			TUint32 &	aValue
		)

Reads an unsigned integer value located in a specific column within the template record and copies it into the specified unsigned integer. The column is identified by the name supplied in the descriptor aColumn.

The CommsDbServer 10 panic is also raised if this function is called after the view has been closed.

If the template record does not exist then the function leaves with KErrUnknown.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of the column in the template record whose (unsigned integer) value is to be read.
TUint32 & aValue	A reference to an unsigned integer passed by the caller.

Reposition()

TInt

Reposition

(

)

[private]

SetHiddenMask()

TBool

SetHiddenMask

(

)

[private]

StoreModifications()

IMPORT_C TInt

StoreModifications

(

)

Stores an new or updated template back to the database.

Confirms changes made to the template record which were started by a call to Modify().

A call to Modify() must have previously been made otherwise the function raises a CommsDbServer 4 panic.

capability: Dependent on table, see the guide page referenced below.

TemplateRecordExists()

IMPORT_C TBool

TemplateRecordExists

(

)

True if a template exists.

Tests whether a template record exists in this table.

WriteBoolL(const TDesC &, const TBool &)

IMPORT_C void	WriteBoolL	(	const TDesC &	aColumn,
			const TBool &	aValue
		)

Writes a specified boolean value to a specific column within the template record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.

The CommsDbServer 12 panic is also raised if this function is called after the view has been closed.

leave: KErrNotFound The column name does not exist.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the template record.
const TBool & aValue	A reference to TBool containing the value to be written into the column.

WriteLongTextL(const TDesC &, const TDesC &)

IMPORT_C void	WriteLongTextL	(	const TDesC &	aColumn,
			const TDesC &	aValue
		)

Writes the long text from a specified descriptor to a specific column within the template record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.

The CommsDbServer 12 panic is also raised if this function is called after the view has been closed.

While the text written by WriteTextL() functions is limited in length, there is no restriction on the length of long text.

leave: KErrNotFound The column name does not exist.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the template record.
const TDesC & aValue	A reference to a descriptor containing the long text to be written into the column.

WriteTextL(const TDesC &, const TDesC8 &)

IMPORT_C void	WriteTextL	(	const TDesC &	aColumn,
			const TDesC8 &	aValue
		)

Writes the narrow (ASCII) text from the specified 8 bit descriptor to a specific column within the template record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.

leave: The function can leave for reasons defined by DBMS. It will also leave if the length of the text is greater than the maximum permitted - equal to the value of the constant KCommsDbSvrMaxColumnNameLength. KErrNotFound The column name does not exist.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the template record.
const TDesC8 & aValue	A reference to an 8 bit descriptor containing the narrow text to be written into the column.

WriteTextL(const TDesC &, const TDesC16 &)

IMPORT_C void	WriteTextL	(	const TDesC &	aColumn,
			const TDesC16 &	aValue
		)

Writes the wide (Unicode) text from the specified 16 bit descriptor to a specific column within the template record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.

The CommsDbServer 12 panic is also raised if this function is called after the view has been closed.

leave: The function can leave for reasons defined by DBMS. It will also leave if the length of the text is greater than the maximum permitted - equal to the value of the constant KCommsDbSvrMaxColumnNameLength. KErrNotFound The column name does not exist.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the current record.
const TDesC16 & aValue	A reference to a 16 bit descriptor containing the wide text to be written into the column.

WriteUintL(const TDesC &, const TUint32 &)

IMPORT_C void	WriteUintL	(	const TDesC &	aColumn,
			const TUint32 &	aValue
		)

Writes a specified unsigned integer value to a specific column within the template record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.

The CommsDbServer 12 panic is also raised if this function is called after the view has been closed.

The column being changed must not be the Id column (symbolic name COMMDB_ID) otherwise the function raises a CommsDbServer 13 panic.

leave: KErrNotFound The column name does not exist.

capability: Dependent on table, see the guide page referenced below.

Parameters

const TDesC & aColumn	A reference to a descriptor containing the name of a column in the template record.
const TUint32 & aValue	A reference to an unsigned integer containing the value to be written into the column.

Member Data Documentation

TBool iRecordExists

TBool

iRecordExists

[private]

CCommsDbTableView * iView

CCommsDbTableView *

iView

[private]