databases::Record Class Reference

Database record base class. More...

#include <record.h>

Inheritance diagram for databases::Record:

databases::NameRecord List of all members.

Public Types

enum  { dbsUpdating = 0x0001, dbsUpdateError = 0x0002, dbsMember = 0x0004, dbsInsert = 0x0008 }
 Possible status flags. More...
typedef uint32_t identifier_type
 Type of the record identifier.

Public Member Functions

 Record ()
 Default constructor.
 Record (identifier_type id)
 Constructor that sets the record identifier.
 Record (Record const &r)
 Copy constructor.
Recordoperator= (Record const &right)
 Assignment operator.
virtual ~Record ()
 Destructor.
bool operator== (identifier_type id)
 Checks whether the given identifier is the same as the record identifier.
virtual void begin_update ()
 Begins record update.
virtual char const * get_s (Field const *field) const
 Gets a string field.
virtual char const * set_s (Field const *field, char const *value)
 Sets a string field.
virtual int32_t get_i (Field const *field) const
 Gets an integer field.
virtual int32_t set_i (Field const *field, int32_t value)
 Sets an integer field.
virtual uint32_t get_ui (Field const *field) const
 Gets an unsigned integer field.
virtual uint32_t set_ui (Field const *field, uint32_t value)
 Sets an unsigned integer field.
virtual time_t get_ut (Field const *field) const
 Gets a Unix timestamp field.
virtual time_t set_ut (Field const *field, time_t value)
 Sets a Unix timestamp field.
virtual identifier_type get_ri (Field const *field) const
 Gets a record identifier field.
virtual identifier_type set_ri (Field const *field, identifier_type value)
 Sets a record identifier field.
virtual bool end_update ()
 Ends record update.
virtual bool owned (Collection const *coll, Record const *record)
 Determines whether this record is owned by another record.
virtual size_t memory_usage () const
 Returns the memory usage of the record.
identifier_type id () const
 Returns the unique identifier of the record.
identifier_type id (identifier_type id)
 Sets the unique identifier of the record.
uint16_t db_status () const
 Returns the status of the record.
uint16_t db_status_add (uint16_t flags)
 Adds flags to the status of the record.
uint16_t db_status_remove (uint16_t flags)
 Removes flags from the status of the record.

Static Public Member Functions

static identifier_type strtori (char const *nptr, char **endptr, int base)
 Converts string record identifier to its integer representation.

Static Public Attributes

static uint32_t const max_id = 0xFFFFFFFF
 The maximum value for an identifier.

Protected Attributes

identifier_type m_id
 The record identifier.
uint16_t m_db_status
 The record status.

Detailed Description

This is a base class for all database records.

Each record gets an unique numeric identifier that may be used to refer to it easily.

The begin_update(), get_s(), set_s(), get_i(), set_i(), get_ui(), set_ui(), get_ut(), set_ut(), get_ri(), set_ri(), end_update(), owned() and memory_usage() functions may be overriden in derived classes.


Member Enumeration Documentation

anonymous enum

Enumerator:
dbsUpdating  The record is being updated by a database module.
dbsUpdateError  Error during the update phase.
dbsMember  The record has been added to its collection.
dbsInsert  The record has been inserted in the database (and has not been deleted).


Member Function Documentation

virtual void databases::Record::begin_update (  )  [virtual]

Begins record update. This function must be called by database modules before they start updating the record.

Once this function has been called successfully, all fields in the record for which a value is available are expected to be updated, in ANY order (and not always in the order they were added to the database), and end_update() MUST be called even if there was an error in the update phase.

The default implementation adds the flags dbsUpdating and dbsInsert (since it is _known_ that the record is indeed in the database) to the record status, and always returns true.

Returns:
true if the database module is allowed to continue its update, false if it must delete the record.

virtual char const* databases::Record::get_s ( Field const *  field  )  const [inline, virtual]

Gets a string field.

The default implementation just returns some undefined value.

Parameters:
[in] field The field to get.
Returns:
The value of the field.

virtual char const* databases::Record::set_s ( Field const *  field,
char const *  value 
) [inline, virtual]

Sets a string field. This function must have been preceded by a call to begin_update().

The default implementation does nothing else than returning the given parameter.

Parameters:
[in] field The field to set.
[in] value The new value for this field.
Returns:
The value of the field, which may be different than the given value; in this case, the database driver must update its stored data to reflect the real value of the field.

virtual int32_t databases::Record::get_i ( Field const *  field  )  const [inline, virtual]

Gets an integer field.

The default implementation just returns some undefined value.

Parameters:
[in] field The field to get.
Returns:
The value of the field.

virtual int32_t databases::Record::set_i ( Field const *  field,
int32_t  value 
) [inline, virtual]

Sets an integer field. This function must have been preceded by a call to begin_update().

The default implementation does nothing else than returning the given parameter.

Parameters:
[in] field The field to update.
[in] value The new value for this field.
Returns:
The value of the field, which may be different than the given value; in this case, the database driver must update its stored data to reflect the real value of the field.

virtual uint32_t databases::Record::get_ui ( Field const *  field  )  const [inline, virtual]

Gets an unsigned integer field.

The default implementation just returns some undefined value.

Parameters:
[in] field The field to get.
Returns:
The value of the field.

virtual uint32_t databases::Record::set_ui ( Field const *  field,
uint32_t  value 
) [inline, virtual]

Sets an unsigned integer field. This function must have been preceded by a call to begin_update().

The default implementation does nothing else than returning the given parameter.

Parameters:
[in] field The field to update.
[in] value The new value for this field.
Returns:
The value of the field, which may be different than the given value; in this case, the database driver must update its stored data to reflect the real value of the field.

virtual time_t databases::Record::get_ut ( Field const *  field  )  const [inline, virtual]

Gets a Unix timestamp field.

The default implementation just returns some undefined value.

Parameters:
[in] field The field to get.
Returns:
The value of the field.

virtual time_t databases::Record::set_ut ( Field const *  field,
time_t  value 
) [inline, virtual]

Sets a Unix timestamp field. This function must have been preceded by a call to begin_update().

The default implementation does nothing else than returning the given parameter.

Parameters:
[in] field The field to update.
[in] value The new value for this field.
Returns:
The value of the field, which may be different than the given value; in this case, the database driver must update its stored data to reflect the real value of the field.

virtual identifier_type databases::Record::get_ri ( Field const *  field  )  const [inline, virtual]

Gets a record identifier field.

The default implementation just returns some undefined value.

Parameters:
[in] field The field to get.
Returns:
The value of the field.

virtual identifier_type databases::Record::set_ri ( Field const *  field,
identifier_type  value 
) [inline, virtual]

Sets a record identifier field. This function must have been preceded by a call to begin_update().

The default implementation does nothing else than returning the given parameter.

Parameters:
[in] field The field to update.
[in] value The new value for this field.
Returns:
The value of the field, which may be different than the given value; in this case, the database driver must update its stored data to reflect the real value of the field.

virtual bool databases::Record::end_update (  )  [virtual]

Ends record update. This function must be called by database modules after they finish updating the record (begin_update() is therefore expected to have been called successfully before).

The default implementation removes the flag dbsUpdating from the record status, and returns true, unless the dbsUpdateError flag has been set, in which case the flag is cleared and the function returns false.

Returns:
true if the update completed successfully, false if the database module must delete the record.

virtual bool databases::Record::owned ( Collection const *  coll,
Record const *  record 
) [inline, virtual]

Determines whether this record is owned by another record.

The default implementation always returns false, so this has to be changed if the collection this records belongs to is owned by another collection.

Parameters:
[in] coll The owner collection.
[in] record The record of the owner collection being deleted.
Returns:
true if this record is owned by the given record, false otherwise.
See also:
remove_owned()

virtual size_t databases::Record::memory_usage (  )  const [inline, virtual]

Returns the memory usage of the record.

The default implementation always returns zero.

Returns:
The memory usage of the record.

identifier_type databases::Record::id ( identifier_type  id  ) 

Sets the unique identifier of the record.

Parameters:
[in] id The unique identifier.
Returns:
The unique identifier of the record (which may be different than id if one was already set.)

uint16_t databases::Record::db_status_add ( uint16_t  flags  )  [inline]

Adds flags to the status of the record.

Parameters:
[in] flags The flags to add.
Returns:
The new record status.

uint16_t databases::Record::db_status_remove ( uint16_t  flags  )  [inline]

Removes flags from the status of the record.

Parameters:
[in] flags The flags to remove.
Returns:
The new record status.


The documentation for this class was generated from the following file:
Generated on Wed Aug 15 00:37:23 2007 for Epona API by  doxygen 1.5.2