Class CCommsDbTableView

class CCommsDbTableView : public CBase;

Support

Supported from 5.0

Description

The view on a specific table.

It includes the necessary behaviour for navigating through the records in the view as well containing member functions for reading and writing to columns within a record.

Implements actions on tables and records in the database. Uses a CCommsDatabase and has an RDbView to read from and write to database. Created via the CCommsDatabase::OpenTableLC() (to open a view of all the records in the table) or one of the OpenViewLC...() functions (to open a specific view of the table).

• CCommsDatabase::OpenTableLC()

• CCommsDatabase::OpenViewMatchingUintLC()

• CCommsDatabase::OpenViewMatchingBoolLC()

• CCommsDatabase::OpenViewMatchingTextLC()

• CCommsDatabase::OpenViewLC()

Derivation

CBase Base class for all classes to be instantiated on the heap CCommsDbTableView The view on a specific table

Defined in CCommsDbTableView:
CCommsDbTableView(), CancelRecordChanges(), CancelRecordChanges(), DeleteRecord(), GetTableName(), GotoFirstRecord(), GotoNextRecord(), GotoPreviousRecord(), InsertRecord(), NewL(), PutRecordChanges(), PutRecordChanges(), ReadBoolL(), ReadColumnLengthL(), ReadLongTextLC(), ReadTextL(), ReadTextL(), ReadTypeAttribL(), ReadUintL(), SetNullL(), UpdateRecord(), WriteBoolL(), WriteLongTextL(), WriteTextL(), WriteTextL(), WriteUintL(), ~CCommsDbTableView()

Inherited from CBase:
operator new()

static CCommsDbTableView* NewL(CCommsDatabaseBase& aDb, const TDesC& aTableName, const TDbQuery& aQuery, TBool aUseTemplate=ETrue);

Description

Low level view creation. Use if CCommsDatabase::OpenTableLC() or CCommsDatabase::OpenViewLC...() are not sufficient.

Parameters

CCommsDatabaseBase& aDb Reference to the instance of the Comms Database to use. const TDesC& aTableName Name of the table of view. const TDbQuery& aQuery Query to perform. TBool aUseTemplate=ETrue Use the template values from the database.

Return value

CCommsDbTableView * A reference to the newly created view.

CCommsDbTableView(CCommsDatabaseBase& aDb, const TDesC& aTableName);

Description

Constructor.

Parameters

CCommsDatabaseBase& aDb Reference to the instance of the Comms Data Base. const TDesC& aTableName The name of the table to view.

~CCommsDbTableView();

Description

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

TInt GotoFirstRecord();

Description

Sets the first record in the view as the current record; i.e. set the view's cursor to point to the first record.

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

Return value

TInt KErrNone if the record exists in the view and navigation is successful, KErrNotFound if the view is empty and has no records, otherwise another of the system-wide error codes.

Notes:

• This function must not be called if any of the operations involved in inserting or updating a record are still outstanding, otherwise the function raises a CommsDbServer 6 panic. For example, the panic is raised if this function is called between calls to UpdateRecord() and PutRecordChanges().

TInt GotoNextRecord();

Description

Sets the next record in the view as the current record; i.e. set the view's cursor to point to the next record.

Return value

TInt KErrNone if the record exists in the view and navigation is successful, KErrNotFound if the current record is already the last in the view and there is no 'next' record, otherwise another of the system-wide error codes.

Notes:

• This function must not be called if any of the operations involved in inserting or updating a record are still outstanding, otherwise the function raises a CommsDbServer 7 panic. For example, the panic is raised if this function is called between calls to UpdateRecord() and PutRecordChanges().
• The CommsDbServer 7 panic is also raised if this function is called after the view has been closed.

TInt GotoPreviousRecord();

Description

Sets the previous record in the view as the current record; i.e. set the view's cursor to point to the previous record.

Return value

TInt KErrNone if the record exists in the view and navigation is successful, KErrNotFound if the current record is already the first in the view and there is no 'previous' record, otherwise another of the system-wide error codes.

Notes:

• This function must not be called if any of the operations involved in inserting or updating a record are still outstanding, otherwise the function raises a CommsDbServer 8 panic. For example, the panic is raised if this function is called between calls to UpdateRecord() and PutRecordChanges().
• The CommsDbServer 8 panic is also raised if this function is called after the view has been closed.

TInt InsertRecord(TUint32& aId);

Description

Prepares database to insert a new record — must be called to ad new entry. This function sets the CCommsDbTableView onto the new record.

Once all changes to the new record are complete, a call must be made to either PutRecordChanges() or CancelRecordChanges() as appropriate.

The function puts the unique Id associated with this new record in aId.

Parameters

TUint32& aId A reference to an unsigned integer passed by the caller. On successful return from this function, contains the unique Id associated with this new record.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Leave codes

The function leaves with KErrOverflow , if the table is either the modem preferences table or the connected modem table and a record already exists.

Notes:

• This function raises a CommsDbServer 1 panic if a previous call to InsertRecord() or UpdateRecord() has already been made.
• This function must be called before any attempt is made to write to a new 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 PutRecordChanges() or CancelRecordChanges() has been called to complete the record insertion operation, otherwise the read operations raise a CommsDbServer 10 panic.

TInt UpdateRecord();

Description

Prepares to update the current record — must be called before editing any existing column.

Once all changes to the new record are complete, a call must be made to either PutRecordChanges() or CancelRecordChanges() as appropriate.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Notes:

• This function raises a CommsDbServer 2 panic if a previous call to InsertRecord() or UpdateRecord() has already been made.
• This function must be called before any attempt is made before editing any existing 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 PutRecordChanges() or CancelRecordChanges() has been called to complete the record insertion operation, otherwise the read operations raise a CommsDbServer 10 panic.

TInt DeleteRecord();

Description

Deletes the record at the current cursor position.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Notes:

• This function raises a CommsDbServer 3 panic if a previous call to InsertRecord() or UpdateRecord() has been made.

TInt PutRecordChanges(TBool aHidden=EFalse, TBool aReadOnly =EFalse);

Support

Supported from 6.0

Description

Confirms changes made to a record which were started by calls to one of InsertRecord() or UpdateRecord().

The record can be marked as hidden by passing ETrue as a parameter. By default, records are not hidden.

Parameters

TBool aHidden Defines whether or not the record is to be marked as hidden. A true value means that the record is to be hidden. If not explicitly specified, EFalse is taken as default. TBool aReadOnly Defines whether or not the record is to be stored as read-only. Read-only storage prevents the record from being altered at a later time.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Notes:

• A call to one of either InsertRecord() or UpdateRecord() must have previously been made otherwise the function raises a CommsDbServer 4 panic.

TInt PutRecordChanges(TBool aHidden=EFalse);

Support

Withdrawn in 6.0

Description

Confirms changes made to a record which were started by calls to one of InsertRecord() or UpdateRecord().

The record can be marked as hidden by passing ETrue as a parameter. By default, records are not hidden.

Parameters

TBool aHidden Defines whether or not the record is to be marked as hidden. A true value means that the record is to be hidden. If not explicitly specified, EFalse is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Notes:

• A call to one of either InsertRecord() or UpdateRecord() must have previously been made otherwise the function raises a CommsDbServer 4 panic.

void CancelRecordChanges();

Support

Supported from 6.0

Description

Abandons changes made to a record which were started by calls to either:InsertRecord() or UpdateRecord().

Notes:

• A call to one of either InsertRecord() or UpdateRecord() must have previously been made otherwise the function raises a CommsDbServer 5 panic.

TInt CancelRecordChanges();

Support

Withdrawn in 6.0

Description

Abandons changes made to a record which were started by calls to either: InsertRecord() or UpdateRecord().

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Notes:

• A call to one of either InsertRecord() or UpdateRecord() must have previously been made otherwise the function raises a CommsDbServer 5 panic.

void ReadTypeAttrib(const TDesC& aColumn, TDbColType& aColType, TUint32& aAttrib);

Description

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

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

Parameters

const TDesC& aColumn A reference to a descriptor containing the name of the column in the current 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.

Leave codes

KErrNotFound Specified column does not exist in the table

Notes:

• This function must not be called if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

If the column in the current record has a NULL value and the table has a template record, then the unsigned integer value located in the corresponding column in that template record is read and copied into aValue.

If the column in the current record has a NULL value and the table does not have a template record, then the function leaves.

Parameters

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

Leave codes

KErrUnknown Specified column is null KErrNotFound Specified column does not exist in the table

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

If the column in the current record has a NULL value and the table has a template record, then the value located in the corresponding column in that template record is read and copied into aValue.

If the column in the current record has a NULL value and the table does not have a template record, then the function leaves.

Parameters

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

Leave codes

KErrUnknown Specified column is null KErrNotFound Specified column does not exist in the table

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

If the column in the current record has a NULL value and the table has a template record, then the text located in the corresponding column in that template record is read and copied into aValue.

If the column in the current record has a NULL value and the table does not have a template record, then the length of the descriptor aValue is set to zero and the descriptor contains no text.

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.

Parameters

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

Leave codes

KErrNotFound Specified column does not exist in the table

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

If the column in the current record has a NULL value and the table has a template record, then the text located in the corresponding column in that template record is read and copied into aValue.

If the column in the current record has a NULL value and the table does not have a template record, then the length of the descriptor aValue is set to zero and the descriptor contains no text.

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.

Parameters

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

Leave codes

KErrNotFound Specified column does not exist in the table

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

HBufC* ReadLongTextLC(const TDesC& aColumn);

Description

Reads the long text located in a specific column within the current 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.

If the column in the current record has a NULL value and the table has a template record, then the long text located in the corresponding column in that template record is read and copied.

If the column in the current record has a NULL value and the table does not have a template record, then the length of the returned heap descriptor is zero and the descriptor contains no text.

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

The HBufC* returned is left on the cleanup stack. The caller is responsible for calling CleanupStack::PopAndDestroy().

Parameters

const TDesC& aColumn A reference to a descriptor containing the name of a column in the current record.

Return value

HBufC* Pointer to a heap descriptor containing the long text.

Leave codes

KErrNotFound Specified column does not exist in the table. KErrNoMemory Out of memory Other system-wide error codes.

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

If the length of the column is zero and the table has a template record, then the length of the corresponding column in that template record is copied into aValue.

Parameters

const TDesC& aColumn A reference to a descriptor containing the name of a column in the current 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.

Leave codes

KErrNotFound Specified column does not exist in the table

Notes:

• This read operation must not occur if any of the operations involved in inserting or updating 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 UpdateRecord() and PutRecordChanges().
• This panic is also raised if this function is called after the view has been closed.

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

Description

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

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. If the column identified is the COMMDB_ID field, than this function raises a CommsDbServer 13 panic. This panic is also raised if this function is called after the view has been closed.

Parameters

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

Leave codes

KErrNotFound The column name does not exist. The function can leave for reasons defined by DBMS.

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

Description

Writes a Boolean value to a specific column within the current record. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. If the column identified is the COMMDB_ID field, than this function raises a CommsDbServer 13 panic. This panic is also raised if this function is called after the view has been closed.

Parameters

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

Leave codes

KErrNotFound The column name does not exist. The function can leave for reasons defined by DBMS.

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

Description

Writes the narrow (ASCII) text from an 8 bit descriptor to a specific column within the current record. The column is identified by the name supplied in the descriptor aColumn. The length of the text cannot be greater than the value of the constant KCommsDbSvrMaxColumnNameLength, otherwise the function leaves.

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. If the column identified is the COMMDB_ID field, than this function raises a CommsDbServer 13 panic.

Parameters

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

Leave codes

KErrOverflow The function can leave for reasons defined by DBMS but it also leaves with KErrOverflow if the length of the text is greater than the maximum permitted. KErrNotFound The column name does not exist. The function can leave for reasons defined by DBMS.

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

Description

Writes the wide (UNICODE) text from a 16 bit descriptor to a specific column within the current record. The column is identified by the name supplied in the descriptor aColumn. The length of the text cannot be greater than the value of the constant KCommsDbSvrMaxColumnNameLength, otherwise the function leaves.

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. If the column identified is the COMMDB_ID field, than this function raises a CommsDbServer 13 panic. This panic is also raised if this function is called after the view has been closed.

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.

Leave codes

The function can leave for reasons defined by DBMS but it also leaves with KErrOverflow, if the length of the text is greater than the maximum permitted. KErrNotFound The column name does not exist. The function can leave for reasons defined by DBMS.

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

Description

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

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. If the column identified is the COMMDB_ID field, than this function raises a CommsDbServer 13 panic. This 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.

Parameters

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

Leave codes

KErrNotFound The column name does not exist. The function can leave for reasons defined by DBMS.

void SetNullL(const TDesC& aColumn);

Description

Sets a specific column within the current record to NULL. For text type columns, this is the same as setting the column to an empty string. The column is identified by the name supplied in the descriptor aColumn.

An earlier call to either UpdateRecord() or InsertRecord() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic. This panic is also raised if this function is called after the view has been closed.

Parameters

const TDesC& aColumn A reference to a descriptor containing the name of a column in the current record.

void GetTableName(TDes& aTableName) const;

Description

Gets the name of the table associated with this view and copies 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.