![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behavior |
CCommsDbTemplateRecord |
Access to a template record in a specific table |
cdbtemp.h
commdb.lib
This class encapsulates the view on 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.
static CCommsDbTemplateRecord* NewL(CCommsDatabase* aDb,const TDesC& aTableName);
Use this static function to allocate and construct this view on the table whose name is defined in the descriptor aTableName and which is in the communications database *aDb.
The view is restricted to the single template record in the table.
The communications database, pointed to by aDb should already have been opened.
Not all tables support template records; if this function is called for a table which does not support template records, then it leaves with KErrNotSupported.
If there is insufficient memory available to create the object, the function leaves. If allocation is successful, it returns a pointer to the new object.
CCommsDatabase* 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. |
CCommsDbTemplateRecord* |
A pointer to the view object which just includes the template record. |
The function may leave for a number of reasons, for example, if the table does not exist or the named table does not support a template record.
~CCommsDbTemplateRecord();
The destructor frees all resources owned by this object, prior to its destruction.
Specifically, it closes the view.
TBool TemplateRecordExists();
Use this function to determine whether a template record exists in this table.
TBool |
true, if a template record exists; false, otherwise |
TInt Modify();
Use this function to prepare to update the template record, if it exists. If the template record does not exist, it is created.
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.
TInt |
KErrNone if successful, otherwise one of the system error codes. |
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.
TInt Delete();
Use this function to delete the template record.
TInt |
KErrNone if successful, otherwise one of the system error codes. |
This function raises a CommsDbServer 3 panic if a previous call to Modify() has been made.
TInt StoreModifications();
Use this function to confirm changes made to the template record which were started by a call to Modify().
TInt |
KErrNone if successful, otherwise one of the system error codes. |
A call to Modify() must have previously been made otherwise the function raises a CommsDbServer 4 panic.
TInt CancelModifications();
Use this function to abandon changes made to the template record which were started by a call to Modify().
TInt |
KErrNone if successful, otherwise one of the system error codes. |
A call to Modify()must have previously been made otherwise the function raises a CommsDbServer 5 panic.
void ReadTypeAttribL(const TDesC& aColumn, TDbColType& aColType, TUint32& aAttrib);
Use this function to fetch the type and the attributes of a specific column within the template 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
.
If the template record does not exist, then the function leaves with KErrNotFound.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the column name cannot be found.
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().
void ReadUintL(const TDesC& aColumn, TUint32& aValue);
Use this function to read an unsigned integer value located in a specific column within the template record and copy it into the unsigned integer aValue. The column is identified by the name supplied in the descriptor aColumn.
If the template record does not exist, then the function leaves with KErrNotFound.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
void ReadBoolL(const TDesC& aColumn, TBool& aValue);
Use this function to read a boolean value located in a specific column within the template record and copy it into the aValue. The column is identified by the name supplied in the descriptor aColumn.
If the template record does not exist, then the function leaves with KErrNotFound.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
void ReadTextL(const TDesC& aColumn, TDes8& aValue);
Use this function to read narrow (ASCII) text located in a specific column within the template 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 template record does not exist, then the function leaves with KErrNotFound.
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.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
void ReadTextL(const TDesC& aColumn, TDes16& aValue);
Use this function to read wide(UNICODE) text located in a specific column within the template 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 template record does not exist, then the function leaves with KErrNotFound.
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.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
void ReadColumnLength(const TDesC& aColumn, TInt& aLength);
Use this function to fetch the length of a specific column within the template record and copy it to aLength. The column is identified by the name supplied in the descriptor aColumn.
If the template record does not exist, then the function leaves with KErrNotFound.
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. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
HBufC* ReadLongTextLC(const TDesC& aColumn);
Use this function to read the long text located in a specific column within the template 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 template record does not exist, then the function leaves with KErrNotFound.
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 attributes.
const TDesC& aColumn |
A reference to a descriptor containing the name of a column in the template record. |
HBufC* |
Pointer to a heap descriptor containing the long text. |
The function can leave for reasons defined by DBMS but it also leaves if the template record does not exist.
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.
void WriteUintL(const TDesC& aColumn, const TUint32& aValue);
Use this function to write the unsigned integer value at aValue 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.
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. |
The column being changed must not be the Id column (symbolic name COMMDB_ID)otherwise the function raises a CommsDbServer 13 panic.
The function can leave for reasons defined by DBMS.
void WriteBoolL(const TDesC& aColumn, const TBool& aValue);
Use this function to write the boolean value at aValue 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.
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. |
The function can leave for reasons defined by DBMS.
void WriteTextL(const TDesC& aColumn, const TDesC8& aValue);
Use this function to write the narrow (ASCII) text from the 8 bit descriptor aValue to a specific column within the template 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 Modify() must have been made before calling this function otherwise the function raises a CommsDbServer 12 panic.
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. |
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.
void WriteTextL(const TDesC& aColumn, const TDesC16& aValue);
Use this function to write the wide (UNICODE) text from the 16 bit descriptor aValue to a specific column within the template 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 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.
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. |
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.
void WriteLongTextL(const TDesC& aColumn, const TDesC& aValue);
Use this function to write the long text from the descriptor aValue 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; see also column attributes.
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. |
The function can leave for reasons defined by DBMS.
void GetTableName(TDes& aTableName) const;
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.
TDes& aTableName |
A reference to a descriptor passed by the caller. On return from this function it contains the name of the table. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |