databases::Collection::Hook Class Reference

Collection hook. More...

#include <collection.h>

List of all members.

Public Types

enum  {
  chsPreAdd = 0x0001, chsPostAdd = 0x0002, chsPreUpdate = 0x0004, chsPostUpdate = 0x0008,
  chsPreRemove = 0x0010, chsPostRemove = 0x0020, chsNameChange = 0x0040
}
 Selector bits. More...

Public Member Functions

 Hook (uint8_t selector)
 Constructor.
 Hook (Hook const &h)
 Copy constructor.
Hookoperator= (Hook const &right)
 Assignment operator.
virtual ~Hook ()
 Destructor.
virtual bool pre_add (Record *record)
 Pre add hook.
virtual void post_add (Record *record)
 Post add hook.
virtual bool pre_update (Record *record, Field const *field)
 Pre update hook.
virtual void post_update (Record *record, Field const *field)
 Post update hook.
virtual bool pre_remove (Record *record)
 Pre-removal hook.
virtual void post_remove (Record *record)
 Post-removal hook.
virtual void name_change (Record *record)
 Name change hook.
uint8_t selector () const
 Returns the notifications this hook gets/wants.


Detailed Description

This class is used as a base class for collection hooks. By inheriting it and overriding its methods, and then adding an object of the derived class to the collection using the Collection::add_hook() function, one may get information about records being added/updated/deleted to/in/from the collection or whose name is being changed.

Member Enumeration Documentation

anonymous enum

Enumerator:
chsPreAdd  Be notified of new records before they are added.
chsPostAdd  Be notified of new records after they have been added.
chsPreUpdate  Be notified of changes in records before they are updated.
chsPostUpdate  Be notified of changes in records after they have been updated.
chsPreRemove  Be notified of removal of records before they are deleted.
chsPostRemove  Be notified of removal of records after they have been deleted.
chsNameChange  Be notified of record name changes (when the collection is a NameCollection).


Constructor & Destructor Documentation

databases::Collection::Hook::Hook ( uint8_t  selector  )  [inline]

Constructor.

Parameters:
[in] selector Determines which notifications this hook gets. An or'ed set of chsPreAdd, chsPostAdd, chsPreUpdate, chsPostUpdate, chsPreRemove, chsPostRemove, chsNameChange


Member Function Documentation

virtual bool databases::Collection::Hook::pre_add ( Record record  )  [inline, virtual]

This method is called prior to adding a record to the collection. Its return value determines whether the record is allowed to be added to the collection.

The default implementation always yields true.

Parameters:
[in] record The new record.
Returns:
true if the record is allowed to be added to the collection, false otherwise.

virtual void databases::Collection::Hook::post_add ( Record record  )  [inline, virtual]

This method is called after a record's been added to the collection.

The default implementation does nothing.

Parameters:
[in] record The new record.

virtual bool databases::Collection::Hook::pre_update ( Record record,
Field const *  field 
) [inline, virtual]

This method is called prior to changing a record in the collection. Its return value determines whether the record is allowed to be altered.

The hook is called by the Collection::change_* function. Because these functions are only called to update a field in the database, only these changes are seen by the hook. Also, some records may not always call these functions when the record is updated by database drivers for the same reasons (there was no need to call these functions when it was known it was a database update), though calling them is now the recommended behaviour in that case, so it's recommended you contact the author of the records so that he/she can make the relevant changes if you need them.

Also, be careful when using this function; it may be dangerous to deny an update when the caller doesn't expect it (indeed, the change_* functions are not expected to fail when there is no database set for the collection, for example), and remember that during a record update from the database driver, returning false there does NOT invalidate the record and thus may make it bogus ! You have to invalidate it explicitly.

The default implementation always yields true.

Parameters:
[in] record The record being changed.
[in] field The field being changed. Usually 0 if the collection doesn't have a database !
Returns:
true if the record is allowed to be added to the collection, false otherwise.

virtual void databases::Collection::Hook::post_update ( Record record,
Field const *  field 
) [inline, virtual]

This method is called after a record's been added to the collection.

The hook is called by the Collection::change_* function. Because these functions are only called to update a field in the database, only these changes are seen by the hook. Also, some records may not always call these functions when the record is updated by database drivers for the same reasons (there was no need to call these functions when it was known it was a database update), though calling them is now the recommended behaviour in that case, so it's recommended you contact the author of the records so that he/she can make the relevant changes if you need them.

The default implementation does nothing.

Parameters:
[in] record The updated record.
[in] field The field being changed. Usually 0 if the collection doesn't have a database !

virtual bool databases::Collection::Hook::pre_remove ( Record record  )  [inline, virtual]

This method is called prior to removing a record from the collection. Its return value determines whether the record is allowed to be removed from the collection.

Note that this is not called when the record is no longer in the database already (which usually happens when removing records owned by other records) as their removals can't be cancelled anymore, obviously.

The default implementation always yields true.

Parameters:
[in] record The record being removed.
Returns:
true if the record is allowed to be removed from the collection, false otherwise.

virtual void databases::Collection::Hook::post_remove ( Record record  )  [inline, virtual]

This hook is called after a record's been removed from the collection.

The default implementation does nothing.

Parameters:
[in] record The removed record.

virtual void databases::Collection::Hook::name_change ( Record record  )  [inline, virtual]

This hook is called when the name of a record is being changed. This operation can't be cancelled as the name has already been updated in the database at this point, though the record's name still points to the old name at this point.

The default implementation does nothing.

Parameters:
[in] record The record whose name is being changed.

uint8_t databases::Collection::Hook::selector (  )  const [inline]

Returns the notifications this hook gets/wants.

Returns:
An or'ed set of chsPreAdd, chsPostAdd, chsPreUpdate, chsPostUpdate, chsPreRemove, chsPostRemove, chsNameChange.


The documentation for this class was generated from the following file:
Generated on Fri Apr 18 22:03:28 2008 for Epona API by  doxygen 1.5.3