EPOC   SDK Home Glossary Indexes Previous Next Up

CCommsDbTableView class


Contents


CCommsDbTableView class — View on a specific table

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behaviour

CCommsDbTableView

View on a specific table

Defined in

commdb.h

Link against

commdb.lib

Description

This class encapsulates 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.

An object of this type cannot be explicitly constructed; it is always constructed, and a pointer to it returned, as a result of a call to one of the following member functions of the CCommsDatabase class:


Destruction


~CCommsDbTableView() — Destructor

~CCommsDbTableView();

Description

The destructor frees all resources owned by this object, prior to its destruction.

Specifically, it closes the view.


Navigating records in the view


GotoFirstRecord() — Set the first record in the view as the current record

TInt GotoFirstRecord();

Description

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

Return Value

TInt

Specifically:

  • KErrNone if the record exists in the view and navigation is successful
  • KErrNotFound if the view is empty and has no records

otherwise one of the system 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().

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


GotoNextRecord() — Set the next record in the view as the current record

TInt GotoNextRecord();

Description

Use this function to set 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

Specifically:

  • 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 one of the system 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.


GotoPreviousRecord() — Set the previous record in the view as the current record

TInt GotoPreviousRecord();

Description

Use this function to set 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

Specifically:

  • 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 one of the system 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.


Making changes to records


InsertRecord() — Prepare to insert a record

TInt InsertRecord(TUint32& aId);

Description

Use this function to prepare to insert a new record.

The function must be called before writing to any column.

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.

Only one record is allowed in the Modem preferences table and the Connected modem table; this function leaves if it is called on either of these tables and a they already have a record.

Arguments

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 one of the system error codes.

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 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.

Leave consideration

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


UpdateRecord() — Prepare to update the current record

TInt UpdateRecord();

Description

Use this function to prepare to update the current record.

The function must be called before writing to any 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 one of the system 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 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 PutRecordChanges() or CancelRecordChanges() has been called to complete the record insertion operation, otherwise the read operations raise a CommsDbServer 10 panic.


DeleteRecord() — Delete the current record

TInt DeleteRecord();

Description

Use this function to delete the record at the current cursor position.

Return Value

TInt

KErrNone if successful, otherwise one of the system error codes.

Notes

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


PutRecordChanges() — Confirm changes to a record

TInt PutRecordChanges(TBool aHidden =EFalse);

Description

Use this function to confirm 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 hidden.

Arguments

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 one of the system 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.


CancelRecordChanges() — Abandon changes to a record

TInt CancelRecordChanges();

Description

Use this function to abandon changes made to a record which were started by calls to either: InsertRecord() or UpdateRecord().

Return Value

TInt

KErrNone if successful, otherwise one of the system 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.


Reading data from a column


ReadTypeAttribL() — Fetch column type and column attributes

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

Description

Use this function to fetch the type and the attributes of a specific column within the current record and put them into aColType and aAttrib respectively. The column is identified by the name supplied in the descriptor aColumn.

The column type is described by the TDbColType enumerator defined in d32dbms.h.

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

Arguments

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 considerations

The function leaves if the column cannot be found.

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.


ReadUintL() — Read an unsigned integer from a column

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

Description

Use this function to read an unsigned integer value located in a specific column within the current record and copy it into the unsigned integer aValue. 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.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if:

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.


ReadBoolL() — Read a boolean value from a column

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

Description

Use this function to read a boolean value located in a specific column within the current record and copy it into the aValue. 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.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if:

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.


ReadTextL() — Read narrow text from a column

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

Description

Use this function to read narrow (ASCII) text located in a specific column within the current record and copy it to the 8 bit modifiable descriptor aValue. 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 defined in cdblen.h. The maximum length of aValue supplied by the caller can, therefore, be the same.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if the column cannot be found.

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.


ReadTextL() — Read wide text from a column

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

Description

Use this function to read wide(UNICODE) text located in a specific column within the current record and copy it to the 16 bit modifiable descriptor aValue. 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 defined in cdblen.h. The maximum length of aValue supplied by the caller can, therefore, be the same.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if the column cannot be found.

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.


ReadColumnLengthL() — Fetch length of column

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

Description

Use this function to fetch the length of a specific column within the current record and copy it to aLength. 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.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if the column cannot be found.

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.


ReadLongTextLC() — Read long text from a column

HBufC* ReadLongTextLC(const TDesC& aColumn);

Description

Use this function to read the long text located in a specific column within the current record and copy 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; see also column type characteristics.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves if the column cannot be found.

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.


Writing data to a column


WriteUintL() — Write an unsigned integer to a column

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

Description

General behviour:

Use this function to write the unsigned integer value at aValue 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. This panic is also raised if this function is called after the view has been closed.

Specific behaviour:

If aColumn is the TSY config ID column, with symbolic name MODEM_TSY_CONFIG_ID and this table is the connected modem table, with symbolic name CONNECTED_MODEM, then the following behaviour occurs:

The following diagram helps to show what's going on.

Specific WriteUintL() behaviour
Arguments

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.

Notes

The column being changed must not be the Id column otherwise the function raises a CommsDbServer 13 panic.

Leave considerations

The function can leave for reasons defined by DBMS.


WriteBoolL() — Write a boolean value to a column

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

Description

Use this function to write the boolean value at aValue 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. This panic is also raised if this function is called after the view has been closed.

Arguments

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 considerations

The function can leave for reasons defined by DBMS.


WriteTextL() — Write narrow text to a column

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

Description

Use this function to write the narrow (ASCII) text from the 8 bit descriptor aValue 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 defined in cdblen.h, 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.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves, if the length of the text is greater than the maximum permitted.


WriteTextL() — Write wide text to a column

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

Description

Use this function to write the wide (UNICODE) text from the 16 bit descriptor aValue 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 defined in cdblen.h, 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. This panic is also raised if this function is called after the view has been closed.

Arguments

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 considerations

The function can leave for reasons defined by DBMS but it also leaves, if the length of the text is greater than the maximum permitted.


WriteLongTextL() — Write long text to a column

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

Description

Use this function to write the long text from the descriptor aValue 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. 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; see also column types and attributes.

Arguments

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 considerations

The function can leave for reasons defined by DBMS.


SetNullL() — Set a column to NULL

void SetNullL(const TDesC& aColumn);

Description

Use this function to set 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.

Arguments

const TDesC& aColumn

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


Get name of the table


GetTableName() — Fetch the name of the table associated with this view

void GetTableName(TDes& aTableName) const;

Description

Use this function to fetch the name of the table associated with this view and copy it into the descriptor aTableName supplied by the caller.

Arguments

TDes& aTableName

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

EPOC       SDK Home Glossary Indexes Previous Next Up