TrackingSyncSource Class Reference
#include <TrackingSyncSource.h>
Classes | |
| class | InsertItemResult |
Public Types | |
| typedef map< string, string > | RevisionMap_t |
Public Member Functions | |
| TrackingSyncSource (const EvolutionSyncSourceParams ¶ms) | |
| virtual Databases | getDatabases ()=0 |
| virtual void | open ()=0 |
| virtual void | exportData (ostream &out) |
| virtual void | listAllItems (RevisionMap_t &revisions)=0 |
| virtual InsertItemResult | insertItem (const string &uid, const SyncItem &item)=0 |
| virtual SyncItem * | createItem (const string &uid)=0 |
| virtual void | deleteItem (const string &uid)=0 |
| virtual void | flush () |
| virtual void | close ()=0 |
| virtual string | fileSuffix () const =0 |
| virtual const char * | getMimeType () const =0 |
| virtual const char * | getMimeVersion () const =0 |
| virtual const char * | getSupportedTypes () const =0 |
Protected Member Functions | |
| virtual void | logItem (const string &uid, const string &info, bool debug=false)=0 |
| virtual void | logItem (const SyncItem &item, const string &info, bool debug=false)=0 |
| virtual void | setItemStatusThrow (const char *key, int status) |
Detailed Description
This class implements change tracking. Data sources which want to use this functionality have to provide the following functionality by implementing the pure virtual functions below:- open() the data
- enumerate all existing items
- provide UID and "revision string": The UID must remain *constant* when the user edits an item (it may change when SyncEvolution changes an item), whereas the revision string must *change* each time the item is changed by anyone. Both can be arbitrary strings, but keeping them simple (printable ASCII, no white spaces, no equal sign) makes debugging simpler because they can be stored as they are as key/value pairs in the sync source's change tracking config node (the .other.ini files when using file-based configuration). More complex strings use escape sequences introduced with an exclamation mark for unsafe characters.
- import/export/update single items
- persistently store all changes in flush()
- clean up in close()
A derived class may (but doesn't have to) override additional functions to modify or replace the default implementations, e.g.:
- dumping the complete database (export())
Potential implementations of the revision string are:
- a modification time stamp
- a hash value of a textual representation of the item (beware, such a hash might change as the textual representation changes even though the item is unchanged)
Definition at line 61 of file TrackingSyncSource.h.
Member Typedef Documentation
| typedef map<string, string> TrackingSyncSource::RevisionMap_t |
Definition at line 90 of file TrackingSyncSource.h.
Constructor & Destructor Documentation
| TrackingSyncSource::TrackingSyncSource | ( | const EvolutionSyncSourceParams & | params | ) |
Creates a new tracking sync source.
Definition at line 25 of file TrackingSyncSource.cpp.
Member Function Documentation
| virtual void TrackingSyncSource::close | ( | ) | [pure virtual] |
closes the data source so that it can be reopened
Just as open() it should not affect the state of the database unless some previous action requires it.
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| virtual SyncItem* TrackingSyncSource::createItem | ( | const string & | uid | ) | [pure virtual] |
Extract information for the item identified by UID and store it in a new SyncItem. The caller must free that item. May throw exceptions.
- Parameters:
-
uid identifies the item
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, EvolutionMemoSource, FileSyncSource, and SQLiteContactSource.
Referenced by exportData().
| virtual void TrackingSyncSource::deleteItem | ( | const string & | uid | ) | [pure virtual] |
removes and item
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| void TrackingSyncSource::exportData | ( | ostream & | out | ) | [virtual] |
exports all items one after the other, separated by blank line; if that format is not suitable, then the derived class must override this call
Implements EvolutionSyncSource.
Reimplemented in AddressBookSource, and EvolutionCalendarSource.
Definition at line 130 of file TrackingSyncSource.cpp.
References createItem(), and listAllItems().
| virtual string TrackingSyncSource::fileSuffix | ( | ) | const [pure virtual] |
file suffix for database files
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| virtual void TrackingSyncSource::flush | ( | ) | [inline, virtual] |
optional: write all changes, throw error if that fails
This is called while the sync is still active whereas close() is called afterwards. Reporting problems as early as possible may be useful at some point, but currently doesn't make a relevant difference.
Reimplemented in AddressBookSource.
Definition at line 173 of file TrackingSyncSource.h.
| virtual Databases TrackingSyncSource::getDatabases | ( | ) | [pure virtual] |
returns a list of all know sources for the kind of items supported by this sync source
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| virtual const char* TrackingSyncSource::getMimeType | ( | ) | const [pure virtual] |
Returns the preferred mime type of the items handled by the sync source. Example: "text/x-vcard"
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, EvolutionMemoSource, FileSyncSource, and SQLiteContactSource.
| virtual const char* TrackingSyncSource::getMimeVersion | ( | ) | const [pure virtual] |
Returns the version of the mime type used by client. Example: "2.1"
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, EvolutionMemoSource, FileSyncSource, and SQLiteContactSource.
| virtual const char* TrackingSyncSource::getSupportedTypes | ( | ) | const [pure virtual] |
A string representing the source types (with versions) supported by the SyncSource. The string must be formatted as a sequence of "type:version" separated by commas ','. For example: "text/x-vcard:2.1,text/vcard:3.0". The version can be left empty, for example: "text/x-s4j-sifc:". Supported types will be sent as part of the DevInf.
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, EvolutionMemoSource, FileSyncSource, and SQLiteContactSource.
| virtual InsertItemResult TrackingSyncSource::insertItem | ( | const string & | uid, | |
| const SyncItem & | item | |||
| ) | [pure virtual] |
Create or modify an item.
The sync source should be flexible: if the UID is non-empty, it shall modify the item referenced by the UID. If the UID is empty, the normal operation is to add it. But if the item already exists (e.g., a calendar event which was imported by the user manually), then the existing item should be updated also in the second case.
Passing a UID of an item which does not exist is an error. This error should be reported instead of covering it up by (re)creating the item.
Errors are signalled by throwing an exception. Returning empty strings in the result is an error which triggers an "item could not be stored" error.
- Parameters:
-
uid identifies the item to be modified, empty for creating item contains the new content of the item and its MIME type
- Returns:
- the result of inserting the item
Implemented in AddressBookSource, EvolutionCalendarSource, EvolutionMemoSource, FileSyncSource, and SQLiteContactSource.
| virtual void TrackingSyncSource::listAllItems | ( | RevisionMap_t & | revisions | ) | [pure virtual] |
fills the complete mapping from UID to revision string of all currently existing items
Usually both UID and revision string must be non-empty. The only exception is a refresh-from-client: in that case the revision string may be empty. The implementor of this call cannot know whether empty strings are allowed, therefore it should not throw errors when it cannot create a non-empty string. The caller of this method will detect situations where a non-empty string is necessary and none was provided.
Referenced by exportData().
| virtual void TrackingSyncSource::logItem | ( | const SyncItem & | item, | |
| const string & | info, | |||
| bool | debug = false | |||
| ) | [protected, pure virtual] |
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| virtual void TrackingSyncSource::logItem | ( | const string & | uid, | |
| const string & | info, | |||
| bool | debug = false | |||
| ) | [protected, pure virtual] |
log a one-line info about an item
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| virtual void TrackingSyncSource::open | ( | ) | [pure virtual] |
Actually opens the data source specified in the constructor, will throw the normal exceptions if that fails. Should not modify the state of the sync source: that can be deferred until the server is also ready and beginSync() is called.
Implements EvolutionSyncSource.
Implemented in AddressBookSource, EvolutionCalendarSource, FileSyncSource, and SQLiteContactSource.
| void TrackingSyncSource::setItemStatusThrow | ( | const char * | key, | |
| int | status | |||
| ) | [protected, virtual] |
Reimplemented from EvolutionSyncSource.
Reimplemented in EvolutionCalendarSource.
Definition at line 177 of file TrackingSyncSource.cpp.
The documentation for this class was generated from the following files:
- src/core/TrackingSyncSource.h
- src/core/TrackingSyncSource.cpp
