mKCal::ExtendedStorage Class Referenceabstract

This class provides a calendar storage interface. More...

#include <extendedstorage.h>

Inheritance diagram for mKCal::ExtendedStorage:

Public Types

enum  DeleteAction { MarkDeleted , PurgeDeleted }
 Action to be performed on save for deleted incidences. More...
 
typedef QSharedPointer< ExtendedStoragePtr
 A shared pointer to a ExtendedStorage.
 

Public Member Functions

 ExtendedStorage (const ExtendedCalendar::Ptr &cal, bool validateNotebooks=true)
 Constructs a new ExtendedStorage object.
 
virtual ~ExtendedStorage ()
 Destructor.
 
virtual bool open ()=0
 
virtual bool load ()=0
 
virtual bool load (const QString &uid)=0
 Load all incidences sharing the same uid into the memory.
 
bool loadSeries (const QString &uid)
 Load all incidences sharing the same uid into the memory.
 
bool load (const QString &uid, const QDateTime &recurrenceId)
 Load incidence by uid/recid into the memory.
 
virtual bool load (const QDate &date)
 Load incidences at given date into the memory.
 
virtual bool load (const QDate &start, const QDate &end)=0
 Load incidences between given dates into the memory.
 
virtual bool loadIncidenceInstance (const QString &instanceIdentifier)
 Load the incidence matching the given identifier.
 
virtual bool loadNotebookIncidences (const QString &notebookUid)=0
 Load incidences of one notebook into the memory.
 
virtual bool purgeDeletedIncidences (const KCalendarCore::Incidence::List &list, const QString &notebook=QString())=0
 Remove from storage all incidences that have been previously marked as deleted and that matches the UID / RecID of the incidences in list.
 
virtual bool save ()=0
 
virtual bool save (DeleteAction deleteAction)=0
 This is an overload of save() method.
 
virtual bool close ()
 
virtual void calendarModified (bool modified, KCalendarCore::Calendar *calendar)=0
 
virtual void calendarIncidenceAdded (const KCalendarCore::Incidence::Ptr &incidence)=0
 
virtual void calendarIncidenceChanged (const KCalendarCore::Incidence::Ptr &incidence)=0
 
virtual void calendarIncidenceDeleted (const KCalendarCore::Incidence::Ptr &incidence, const KCalendarCore::Calendar *calendar)=0
 
virtual void calendarIncidenceAdditionCanceled (const KCalendarCore::Incidence::Ptr &incidence)=0
 
virtual bool insertedIncidences (KCalendarCore::Incidence::List *list, const QDateTime &after=QDateTime(), const QString &notebookUid=QString())=0
 Get inserted incidences from storage.
 
virtual bool modifiedIncidences (KCalendarCore::Incidence::List *list, const QDateTime &after=QDateTime(), const QString &notebookUid=QString())=0
 Get modified incidences from storage.
 
virtual bool deletedIncidences (KCalendarCore::Incidence::List *list, const QDateTime &after=QDateTime(), const QString &notebookUid=QString())=0
 Get deleted incidences from storage.
 
virtual bool allIncidences (KCalendarCore::Incidence::List *list, const QString &notebookUid=QString())=0
 Get all incidences from storage.
 
virtual bool search (const QString &key, QStringList *identifiers, int limit=0)=0
 Get all incidences from storage that match key.
 
virtual QDateTime incidenceDeletedDate (const KCalendarCore::Incidence::Ptr &incidence)=0
 Get deletion time of incidence.
 
void registerObserver (ExtendedStorageObserver *observer)
 Registers an Observer for this Storage.
 
void unregisterObserver (ExtendedStorageObserver *observer)
 Unregisters an Observer for this Storage.
 
bool addNotebook (const Notebook::Ptr &nb)
 Add new notebook to the storage.
 
bool updateNotebook (const Notebook::Ptr &nb)
 Update notebook parameters.
 
bool deleteNotebook (const Notebook::Ptr &nb)
 Delete notebook from storage.
 
bool setDefaultNotebook (const Notebook::Ptr &nb)
 setDefaultNotebook to the storage.
 
Notebook::Ptr defaultNotebook ()
 defaultNotebook.
 
Notebook::Ptr notebook (const QString &uid) const
 Search for notebook.
 
Notebook::List notebooks ()
 List all notebooks.
 
void setValidateNotebooks (bool validateNotebooks)
 Determine if notebooks should be validated in saves and loads.
 
bool validateNotebooks () const
 Returns true if notebooks should be validated in saves and loads.
 
bool isValidNotebook (const QString &notebookUid) const
 Returns true if the given notebook is valid for the storage.
 
Notebook::Ptr createDefaultNotebook (QString name=QString(), QString color=QString())
 Creates and sets a default notebook.
 
virtual void virtual_hook (int id, void *data)=0
 Standard trick to add virtuals later.
 

Protected Member Functions

virtual bool loadNotebooks ()=0
 
virtual bool insertNotebook (const Notebook::Ptr &nb)=0
 
virtual bool modifyNotebook (const Notebook::Ptr &nb)=0
 
virtual bool eraseNotebook (const Notebook::Ptr &nb)=0
 
bool getLoadDates (const QDate &start, const QDate &end, QDateTime *loadStart, QDateTime *loadEnd) const
 
void addLoadedRange (const QDate &start, const QDate &end) const
 
bool isRecurrenceLoaded () const
 
void setIsRecurrenceLoaded (bool loaded)
 
void emitStorageModified (const QString &info)
 
void emitStorageFinished (bool error, const QString &info)
 
void emitStorageUpdated (const KCalendarCore::Incidence::List &added, const KCalendarCore::Incidence::List &modified, const KCalendarCore::Incidence::List &deleted)
 

Detailed Description

This class provides a calendar storage interface.

Every action on the storage can be synchronous or asynchronous, depending on the storage implementation. SqliteStorage is a synchronous implementation.

In any case, caller can use ExtendedStorageObserver to get notified about the action done.

Member Typedef Documentation

◆ Ptr

A shared pointer to a ExtendedStorage.

Member Enumeration Documentation

◆ DeleteAction

Action to be performed on save for deleted incidences.

Enumerator
MarkDeleted 
PurgeDeleted 

Constructor & Destructor Documentation

◆ ExtendedStorage()

ExtendedStorage::ExtendedStorage ( const ExtendedCalendar::Ptr & cal,
bool validateNotebooks = true )
explicit

Constructs a new ExtendedStorage object.

Private class that helps to provide binary compatibility between releases.

Parameters
calis a pointer to a valid Calendar object.
validateNotebooksset to true for loading/saving only those incidences that belong to an existing notebook of this storage
Warning
Do not use storage as a global object, on closing the application it can dead lock. If you do so, be ready to destroy it manually before the application closes.
Once an Incidence has been added to the ExtendedStorage the UID cannot change. It is possible to do so through the API, but the internal hash tables will not be updated and hence the changes will not be tracked.

◆ ~ExtendedStorage()

ExtendedStorage::~ExtendedStorage ( )
virtual

Destructor.

Member Function Documentation

◆ addLoadedRange()

void ExtendedStorage::addLoadedRange ( const QDate & start,
const QDate & end ) const
protected

◆ addNotebook()

bool ExtendedStorage::addNotebook ( const Notebook::Ptr & nb)

Add new notebook to the storage.

Notebook object is owned by the storage if operation succeeds. Operation is executed immediately into storage,

See also
modifyNotebook().
Parameters
nbnotebook
Returns
true if operation was successful; false otherwise.
Note
if the Notebook doesn't have a uid that is a valid UUID a new one will be generated on insertion.

◆ allIncidences()

virtual bool mKCal::ExtendedStorage::allIncidences ( KCalendarCore::Incidence::List * list,
const QString & notebookUid = QString() )
pure virtual

Get all incidences from storage.

Parameters
listnotebook's incidences
notebookUidlist incidences for given notebook
Returns
true if execution was scheduled; false otherwise

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ calendarIncidenceAdded()

virtual void mKCal::ExtendedStorage::calendarIncidenceAdded ( const KCalendarCore::Incidence::Ptr & incidence)
pure virtual

Calendar::CalendarObserver::calendarIncidenceAdded()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ calendarIncidenceAdditionCanceled()

virtual void mKCal::ExtendedStorage::calendarIncidenceAdditionCanceled ( const KCalendarCore::Incidence::Ptr & incidence)
pure virtual

Calendar::CalendarObserver::calendarIncidenceAdditionCanceled()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ calendarIncidenceChanged()

virtual void mKCal::ExtendedStorage::calendarIncidenceChanged ( const KCalendarCore::Incidence::Ptr & incidence)
pure virtual

Calendar::CalendarObserver::calendarIncidenceChanged()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ calendarIncidenceDeleted()

virtual void mKCal::ExtendedStorage::calendarIncidenceDeleted ( const KCalendarCore::Incidence::Ptr & incidence,
const KCalendarCore::Calendar * calendar )
pure virtual

Calendar::CalendarObserver::calendarIncidenceDeleted()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ calendarModified()

virtual void mKCal::ExtendedStorage::calendarModified ( bool modified,
KCalendarCore::Calendar * calendar )
pure virtual

Calendar::CalendarObserver::calendarModified()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ close()

bool ExtendedStorage::close ( )
virtual

CalStorage::close()

Reimplemented in DummyStorage, and mKCal::SqliteStorage.

◆ createDefaultNotebook()

Notebook::Ptr ExtendedStorage::createDefaultNotebook ( QString name = QString(),
QString color = QString() )

Creates and sets a default notebook.

Usually called for an empty calendar.

Notice: deprecated since 0.6.10. Instead, create a notebook and call setDefaultNotebook().

Parameters
namenotebook's name, if empty default used
colornotebook's color in format "#FF0042", if empty default used
Returns
pointer to the created notebook

◆ defaultNotebook()

Notebook::Ptr ExtendedStorage::defaultNotebook ( )

defaultNotebook.

Returns
pointer to default notebook.

◆ deletedIncidences()

virtual bool mKCal::ExtendedStorage::deletedIncidences ( KCalendarCore::Incidence::List * list,
const QDateTime & after = QDateTime(),
const QString & notebookUid = QString() )
pure virtual

Get deleted incidences from storage.

Parameters
listdeleted incidences
afterlist only incidences deleted after or at given datetime
notebookUidlist only incidences for given notebook
Returns
true if execution was scheduled; false otherwise

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ deleteNotebook()

bool ExtendedStorage::deleteNotebook ( const Notebook::Ptr & nb)

Delete notebook from storage.

Operation is executed immediately into storage,

See also
modifyNotebook().
Parameters
nbnotebook
Returns
true if delete was successful; false otherwise.

◆ emitStorageFinished()

void ExtendedStorage::emitStorageFinished ( bool error,
const QString & info )
protected

◆ emitStorageModified()

void ExtendedStorage::emitStorageModified ( const QString & info)
protected

◆ emitStorageUpdated()

void ExtendedStorage::emitStorageUpdated ( const KCalendarCore::Incidence::List & added,
const KCalendarCore::Incidence::List & modified,
const KCalendarCore::Incidence::List & deleted )
protected

◆ eraseNotebook()

virtual bool mKCal::ExtendedStorage::eraseNotebook ( const Notebook::Ptr & nb)
protectedpure virtual

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ getLoadDates()

bool ExtendedStorage::getLoadDates ( const QDate & start,
const QDate & end,
QDateTime * loadStart,
QDateTime * loadEnd ) const
protected

◆ incidenceDeletedDate()

virtual QDateTime mKCal::ExtendedStorage::incidenceDeletedDate ( const KCalendarCore::Incidence::Ptr & incidence)
pure virtual

Get deletion time of incidence.

Parameters
incidenceincidence to check
Returns
valid deletion time of incidence in UTC if incidence has been deleted otherwise QDateTime()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ insertedIncidences()

virtual bool mKCal::ExtendedStorage::insertedIncidences ( KCalendarCore::Incidence::List * list,
const QDateTime & after = QDateTime(),
const QString & notebookUid = QString() )
pure virtual

Get inserted incidences from storage.

NOTE: time stamps assigned by KCalExtended are created during save(). To obtain a time stamp that is guaranteed to not included recent changes, sleep for a second or increment the current time by a second.

Parameters
listinserted incidences
afterlist only incidences inserted after or at given datetime
notebookUidlist only incidences for given notebook
Returns
true if execution was scheduled; false otherwise

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ insertNotebook()

virtual bool mKCal::ExtendedStorage::insertNotebook ( const Notebook::Ptr & nb)
protectedpure virtual

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ isRecurrenceLoaded()

bool ExtendedStorage::isRecurrenceLoaded ( ) const
protected

◆ isValidNotebook()

bool ExtendedStorage::isValidNotebook ( const QString & notebookUid) const

Returns true if the given notebook is valid for the storage.

That means that storage can load/save incidences on this notebook.

Parameters
notebookUidnotebook uid
Returns
true or false

◆ load() [1/5]

virtual bool mKCal::ExtendedStorage::load ( )
pure virtual

CalStorage::load()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ load() [2/5]

bool ExtendedStorage::load ( const QDate & date)
virtual

Load incidences at given date into the memory.

All incidences that happens within date, or starts / ends within date or span during date are loaded into memory. The time zone used to expand date into points in time is the time zone of the associated calendar. In addition, all recurring events are also loaded into memory since there is no way to know in advance if they will have occurrences intersecting date. Internally, recurring incidences and incidences of date are cached to avoid loading them several times.

Parameters
datedate
Returns
true if the load was successful; false otherwise.

◆ load() [3/5]

virtual bool mKCal::ExtendedStorage::load ( const QDate & start,
const QDate & end )
pure virtual

Load incidences between given dates into the memory.

start is inclusive, while end is exclusive. The same definitions and restrictions for loading apply as for load(const QDate &) method.

Parameters
startis the starting date
endis the ending date, exclusive
Returns
true if the load was successful; false otherwise.

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ load() [4/5]

virtual bool mKCal::ExtendedStorage::load ( const QString & uid)
pure virtual

Load all incidences sharing the same uid into the memory.

Parameters
uidis uid of the series
Returns
true if the load was successful; false otherwise.

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ load() [5/5]

bool ExtendedStorage::load ( const QString & uid,
const QDateTime & recurrenceId )

Load incidence by uid/recid into the memory.

This method is deprecated since it may populate calendars with orphaned exceptions, or recurring event without their exceptions.

Use load(const QString &uid) which ensures for recurring incidences to also get their exceptions.

Parameters
uidis uid of incidence
recurrenceidis recurrenceid of incidence
Returns
true if the load was successful; false otherwise.

◆ loadIncidenceInstance()

bool ExtendedStorage::loadIncidenceInstance ( const QString & instanceIdentifier)
virtual

Load the incidence matching the given identifier.

This method may be more fragile than load(uid, recid) though since the instanceIdentifier is not saved as is in the database.

Parameters
instanceIdentifieris an identifier returned by Incidence::instanceIdentifier()
Returns
true if the load was successful; false otherwise.

◆ loadNotebookIncidences()

virtual bool mKCal::ExtendedStorage::loadNotebookIncidences ( const QString & notebookUid)
pure virtual

Load incidences of one notebook into the memory.

Parameters
notebookUidis uid of notebook
Returns
true if the load was successful; false otherwise.

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ loadNotebooks()

virtual bool mKCal::ExtendedStorage::loadNotebooks ( )
protectedpure virtual

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ loadSeries()

bool ExtendedStorage::loadSeries ( const QString & uid)

Load all incidences sharing the same uid into the memory.

Deprecated call, equivalent to calling load(const QString &uid).

Parameters
uidis uid of the series
Returns
true if the load was successful; false otherwise.

◆ modifiedIncidences()

virtual bool mKCal::ExtendedStorage::modifiedIncidences ( KCalendarCore::Incidence::List * list,
const QDateTime & after = QDateTime(),
const QString & notebookUid = QString() )
pure virtual

Get modified incidences from storage.

NOTE: if an incidence is both created and modified after the given time, it will be returned in insertedIncidences only, not here!

Parameters
listmodified incidences
afterlist only incidences modified after or at given datetime
notebookUidlist only incidences for given notebook
Returns
true if execution was scheduled; false otherwise

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ modifyNotebook()

virtual bool mKCal::ExtendedStorage::modifyNotebook ( const Notebook::Ptr & nb)
protectedpure virtual

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ notebook()

Notebook::Ptr ExtendedStorage::notebook ( const QString & uid) const

Search for notebook.

Parameters
uidnotebook uid
Returns
pointer to notebook

◆ notebooks()

Notebook::List ExtendedStorage::notebooks ( )

List all notebooks.

Returns
list of notebooks

◆ open()

virtual bool mKCal::ExtendedStorage::open ( )
pure virtual

CalStorage::open()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ purgeDeletedIncidences()

virtual bool mKCal::ExtendedStorage::purgeDeletedIncidences ( const KCalendarCore::Incidence::List & list,
const QString & notebook = QString() )
pure virtual

Remove from storage all incidences that have been previously marked as deleted and that matches the UID / RecID of the incidences in list.

The action is performed immediately on database.

Parameters
listis the incidences to remove from the DB
notebookis the notebook they belong to, using an empty notebook uid is deprecated, but kept for backward backward compatibility.
Returns
True on success, false otherwise.

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ registerObserver()

void ExtendedStorage::registerObserver ( ExtendedStorageObserver * observer)

Registers an Observer for this Storage.

Parameters
observeris a pointer to an Observer object that will be watching this Storage.
See also
unregisterObserver()

◆ save() [1/2]

virtual bool mKCal::ExtendedStorage::save ( )
pure virtual

CalStorage::save()

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ save() [2/2]

virtual bool mKCal::ExtendedStorage::save ( DeleteAction deleteAction)
pure virtual

This is an overload of save() method.

When @deleteAction is PurgeDeleted, the deleted incidences are not marked as deleted but completely removed from the database and won't appear anymore when calling deletedIncidences().

Parameters
deleteActionthe action to apply to deleted incidences
Returns
True if successful; false otherwise

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ search()

virtual bool mKCal::ExtendedStorage::search ( const QString & key,
QStringList * identifiers,
int limit = 0 )
pure virtual

Get all incidences from storage that match key.

Incidences are loaded into the associated ExtendedCalendar. More incidences than the listed ones in

Parameters
identifiersmay be loaded into memory to ensure calendar consistency with respect to exceptions of recurring incidences.

Matching is done on summary, description and location fields.

The matching incidences are sorted by start dates before applying the

Parameters
limit.Since recurring incidences have occurrences later than their start date, they are not taken into account when counting the limit and all matching recurring events are always loaded.
keycan be any substring from the summary, the description or the location.
identifiersoptional, stores the instance identifiers of matching incidences.
limitthe maximum number of non-recurring incidences, unlimited by default
Returns
true on success.

Implemented in DummyStorage, and mKCal::SqliteStorage.

◆ setDefaultNotebook()

bool ExtendedStorage::setDefaultNotebook ( const Notebook::Ptr & nb)

setDefaultNotebook to the storage.

Parameters
nbnotebook
Returns
true if operation was successful; false otherwise.

◆ setIsRecurrenceLoaded()

void ExtendedStorage::setIsRecurrenceLoaded ( bool loaded)
protected

◆ setValidateNotebooks()

void ExtendedStorage::setValidateNotebooks ( bool validateNotebooks)

Determine if notebooks should be validated in saves and loads.

That means that storage can only load/save incidences into/from existing notebooks.

Parameters
validatetrue to validate

◆ unregisterObserver()

void ExtendedStorage::unregisterObserver ( ExtendedStorageObserver * observer)

Unregisters an Observer for this Storage.

Parameters
observeris a pointer to an Observer object that has been watching this Storage.
See also
registerObserver()

◆ updateNotebook()

bool ExtendedStorage::updateNotebook ( const Notebook::Ptr & nb)

Update notebook parameters.

Operation is executed immediately into storage,

See also
modifyNotebook().
Parameters
nbnotebook
Returns
true if add was successful; false otherwise.

◆ validateNotebooks()

bool ExtendedStorage::validateNotebooks ( ) const

Returns true if notebooks should be validated in saves and loads.

That means that storage can only load/save incidences into/from existing notebooks.

Returns
true to validate notebooks

◆ virtual_hook()

virtual void mKCal::ExtendedStorage::virtual_hook ( int id,
void * data )
pure virtual

Standard trick to add virtuals later.

Parameters
idis any integer unique to this class which we will use to identify the method to be called.
datais a pointer to some glob of data, typically a struct.

Implemented in DummyStorage, and mKCal::SqliteStorage.


The documentation for this class was generated from the following files:

Generated on Thu Nov 28 2024 09:02:24 for libextendedkcal by doxygen 1.12.0