2
* Copyright (C) 2005-2009 Patrick Ohly <patrick.ohly@gmx.de>
3
* Copyright (C) 2009 Intel Corporation
5
* This library is free software; you can redistribute it and/or
6
* modify it under the terms of the GNU Lesser General Public
7
* License as published by the Free Software Foundation; either
8
* version 2.1 of the License, or (at your option) version 3.
10
* This library is distributed in the hope that it will be useful,
11
* but WITHOUT ANY WARRANTY; without even the implied warranty of
12
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13
* Lesser General Public License for more details.
15
* You should have received a copy of the GNU Lesser General Public
16
* License along with this library; if not, write to the Free Software
17
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21
#ifndef INCL_SYNCSOURCE
22
#define INCL_SYNCSOURCE
24
#include <syncevo/SyncConfig.h>
25
#include <syncevo/Logging.h>
26
#include <syncevo/SyncML.h>
28
#include <synthesis/sync_declarations.h>
29
#include <synthesis/syerror.h>
30
#include <synthesis/blobs.h>
32
#include <boost/function.hpp>
34
#include <syncevo/declarations.h>
41
* This set of parameters always has to be passed when constructing
42
* SyncSource instances.
44
struct SyncSourceParams {
46
* @param name the name needed by SyncSource
47
* @param nodes a set of config nodes to be used by this source
49
SyncSourceParams(const string &name,
50
const SyncSourceNodes &nodes = SyncSourceNodes()) :
56
SyncSourceNodes m_nodes;
60
* The SyncEvolution core has no knowledge of existing SyncSource
61
* implementations. Implementations have to register themselves
62
* by instantiating this class exactly once with information
65
* It is also possible to add configuration options. For that define a
66
* derived class. In its constructor use
67
* SyncSourceConfig::getRegistry() resp. SyncConfig::getRegistry() to
68
* define new configuration properties. The advantage of registering
69
* them is that the user interface will automatically handle them like
70
* the predefined ones. The namespace of these configuration options
71
* is shared by all sources and the core.
73
* For properties with arbitrary names use the
74
* SyncSourceNodes::m_trackingNode.
76
class RegisterSyncSource
80
* Users select a SyncSource and its data format via the "type"
81
* config property. Backends have to add this kind of function to
82
* the SourceRegistry_t in order to be considered by the
83
* SyncSource creation mechanism.
85
* The function will be called to check whether the backend was
86
* meant by the user. It should return a new instance which will
87
* be freed by the caller or NULL if it does not support the
90
* Inactive sources should return the special InactiveSource
91
* pointer value if they recognize without a doubt that the user
92
* wanted to instantiate them: for example, an inactive
93
* EvolutionContactSource will return NULL for "addressbook" but
94
* InactiveSource for "evolution-contacts".
96
typedef SyncSource *(*Create_t)(const SyncSourceParams ¶ms);
98
/** special return value of Create_t, not a real sync source! */
99
static SyncSource *const InactiveSource;
102
* @param shortDescr a few words identifying the data to be synchronized,
103
* e.g. "Evolution Calendar"
104
* @param enabled true if the sync source can be instantiated,
105
* false if it was not enabled during compilation or is
106
* otherwise not functional
107
* @param create factory function for sync sources of this type
108
* @param typeDescr multiple lines separated by \n which get appended to
109
* the the description of the type property, e.g.
110
* "Evolution Memos = memo = evolution-memo\n"
111
* " plain text in UTF-8 (default) = text/plain\n"
112
* " iCalendar 2.0 = text/calendar\n"
113
* " The later format is not tested because none of the\n"
114
* " supported SyncML servers accepts it.\n"
115
* @param typeValues the config accepts multiple names for the same internal
116
* type string; this list here is added to that list of
117
* aliases. It should contain at least one unique string
118
* the can be used to pick this sync source among all
119
* SyncEvolution sync sources (testing, listing backends, ...).
120
* Example: Values() + (Aliases("Evolution Memos") + "evolution-memo")
122
RegisterSyncSource(const string &shortDescr,
125
const string &typeDescr,
126
const Values &typeValues);
128
const string m_shortDescr;
129
const bool m_enabled;
130
const Create_t m_create;
131
const string m_typeDescr;
132
const Values m_typeValues;
135
typedef list<const RegisterSyncSource *> SourceRegistry;
137
class TestingSyncSource;
140
* Information about a data source. For the sake of simplicity all
141
* items pointed to are owned by the ClientTest and must
142
* remain valid throughout a test session. Not setting a pointer
143
* is okay, but it will disable all tests that need the
146
struct ClientTestConfig{
148
* The name is used in test names and has to be set.
150
const char *sourceName;
153
* A default URI to be used when creating a client config.
158
* A corresponding source name in the default server template,
159
* this is used to copy corresponding uri set in the server template
160
* instead of the uri field above (which is the same for all servers).
162
const char *sourceNameServerTemplate;
165
* A member function of a subclass which is called to create a
166
* sync source referencing the data. This is used in tests of
167
* the SyncSource API itself as well as in tests which need to
168
* modify or check the data sources used during synchronization.
170
* The test framework will call beginSync() and then some of
171
* the functions it wants to test. After a successful test it
172
* will call endSync() which is then expected to store all
173
* changes persistently. Creating a sync source again
174
* with the same call should not report any
175
* new/updated/deleted items until such changes are made via
176
* another sync source.
178
* The instance will be deleted by the caller. Because this
179
* may be in the error case or in an exception handler,
180
* the sync source's desctructor should not thow exceptions.
182
* @param client the same instance to which this config belongs
183
* @param source index of the data source (from 0 to ClientTest::getNumSources() - 1)
184
* @param isSourceA true if the requested SyncSource is the first one accessing that
185
* data, otherwise the second
187
typedef TestingSyncSource *(*createsource_t)(ClientTest &client, int source, bool isSourceA);
190
* Creates a sync source which references the primary database;
191
* it may report the same changes as the sync source used during
194
createsource_t createSourceA;
197
* A second sync source also referencing the primary data
198
* source, but configured so that it tracks changes
199
* independently from the the primary sync source.
201
* In local tests the usage is like this:
202
* - add item via first SyncSource
203
* - iterate over new items in second SyncSource
204
* - check that it lists the added item
206
* In tests with a server the usage is:
207
* - do a synchronization with the server
208
* - iterate over items in second SyncSource
209
* - check that the total number and number of
210
* added/updated/deleted items is as expected
212
createsource_t createSourceB;
215
* The framework can generate vCard and vCalendar/iCalendar items
216
* automatically by copying a template item and modifying certain
219
* This is the template for these automatically generated items.
220
* It must contain the string <<REVISION>> which will be replaced
221
* with the revision parameter of the createItem() method.
223
const char *templateItem;
226
* This is a colon (:) separated list of properties which need
227
* to be modified in templateItem.
229
const char *uniqueProperties;
232
* the number of items to create during stress tests
237
* This is a single property in templateItem which can be extended
238
* to increase the size of generated items.
240
const char *sizeProperty;
243
* Type to be set when importing any of the items into the
244
* corresponding sync sources. Use "" if sync source doesn't
245
* need this information.
247
* Not currently used! All items are assumed to be in the raw,
248
* internal format (see SyncSourceRaw and SyncSourceSerialize).
250
const char *itemType;
253
* A very simple item that is inserted during basic tests. Ideally
254
* it only contains properties supported by all servers.
256
const char *insertItem;
259
* A slightly modified version of insertItem. If the source has UIDs
260
* embedded into the item data, then both must have the same UID.
261
* Again all servers should better support these modified properties.
263
const char *updateItem;
266
* A more heavily modified version of insertItem. Same UID if necessary,
267
* but can test changes to items only supported by more advanced
270
const char *complexUpdateItem;
273
* To test merge conflicts two different updates of insertItem are
274
* needed. This is the first such update.
276
const char *mergeItem1;
279
* The second merge update item. To avoid true conflicts it should
280
* update different properties than mergeItem1, but even then servers
281
* usually have problems perfectly merging items. Therefore the
282
* test is run without expecting a certain merge result.
284
const char *mergeItem2;
287
* These two items are related: one is main one, the other is
288
* a subordinate one. The semantic is that the main item is
289
* complete on it its own, while the other normally should only
290
* be used in combination with the main one.
292
* Because SyncML cannot express such dependencies between items,
293
* a SyncSource has to be able to insert, updated and remove
294
* both items independently. However, operations which violate
295
* the semantic of the related items (like deleting the parent, but
296
* not the child) may have unspecified results (like also deleting
297
* the child). See linkedItemsRelaxedSemantic and sourceKnowsItemSemantic.
299
* One example for main and subordinate items are a recurring
300
* iCalendar 2.0 event and a detached recurrence.
302
const char *parentItem, *childItem;
305
* Backends atomic modification tests
307
bool atomicModification;
310
* set to false to disable tests which slightly violate the
311
* semantic of linked items by inserting children
312
* before/without their parent
314
bool linkedItemsRelaxedSemantic;
317
* setting this to false disables tests which depend
318
* on the source's support for linked item semantic
319
* (testLinkedItemsInsertParentTwice, testLinkedItemsInsertChildTwice)
321
bool sourceKnowsItemSemantic;
324
* called to dump all items into a file, required by tests which need
327
* ClientTest::dump can be used: it will simply dump all items of the source
328
* with a blank line as separator.
330
* @param source sync source A already created and with beginSync() called
331
* @param file a file name
332
* @return error code, 0 for success
334
int (*dump)(ClientTest &client, TestingSyncSource &source, const char *file);
337
* import test items: which these are is determined entirely by
338
* the implementor, but tests work best if several complex items are
341
* ClientTest::import can be used if the file contains items separated by
344
* @param source sync source A already created and with beginSync() called
345
* @param file the name of the file to import
346
* @retval realfile the name of the file that was really imported;
347
* this may depend on the current server that is being tested
348
* @return error code, 0 for success
350
int (*import)(ClientTest &client, TestingSyncSource &source, const char *file, std::string &realfile);
353
* a function which compares two files with items in the format used by "dump"
355
* @param fileA first file name
356
* @param fileB second file name
357
* @return true if the content of the files is considered equal
359
bool (*compare)(ClientTest &client, const char *fileA, const char *fileB);
362
* a file with test cases in the format expected by import and compare
364
const char *testcases;
367
* the item type normally used by the source (not used by the tests
368
* themselves; client-test.cpp uses it to initialize source configs)
373
* a list of sub configs separated via , if this is a super datastore
375
const char *subConfigs;
378
* TRUE if the source supports recovery from an interrupted
379
* synchronization. Enables the Client::Sync::*::Retry group
388
* In addition to registering the sync source itself by creating an
389
* instance of RegisterSyncSource, configurations for testing it can
390
* also be registered. A sync source which supports more than one data
391
* exchange format can register one configuration for each format, but
392
* not registering any configuration is also okay.
394
* *Using* the registered tests depends on the CPPUnit test framework.
395
* *Registering* does not. Therefore backends should always register *
396
* *themselves for testing and leave it to the test runner
397
* "client-test" whether tests are really executed.
399
* Unit tests are different. They create hard dependencies on CPPUnit
400
* inside the code that contains them, and thus should be encapsulated
401
* inside #ifdef ENABLE_UNIT_TESTS checks.
403
* Sync sources have to work stand-alone without a full SyncClient
404
* configuration for all local tests. The minimal configuration prepared
405
* for the source includes:
406
* - a tracking node (as used f.i. by TrackingSyncSource) which
407
* points towards "~/.config/syncevolution/client-test-changes"
408
* - a unique change ID (as used f.i. by EvolutionContactSource)
409
* - a valid "evolutionsource" property in the config node, starting
410
* with the CLIENT_TEST_EVOLUTION_PREFIX env variable or (if that
411
* wasn't set) the "SyncEvolution_Test_" prefix
412
* - "evolutionuser/password" if CLIENT_TEST_EVOLUTION_USER/PASSWORD
415
* No other properties are set, which implies that currently sync sources
416
* which require further parameters cannot be tested.
418
* @warning There is a potential problem with the registration
419
* mechanism. Both the sync source tests as well as the CPPUnit tests
420
* derived from them are registrered when global class instances are
421
* initialized. If the RegisterTestEvolution instance in
422
* client-test-app.cpp is initialized *before* the sync source tests,
423
* then those won't show up in the test list. Currently the right
424
* order seems to be used, so everything works as expected.
426
class RegisterSyncSourceTest
430
* This call is invoked after setting up the config with default
431
* values for the test cases selected via the constructor's
432
* testCaseName parameter (one of vcard21, vcard30, ical20, itodo20;
433
* see ClientTest in the Funambol client library for the current
436
* This call can then override any of the values or (if there
437
* are no predefined test cases) add them.
439
* The "type" property must select your sync source and the
440
* data format for the test.
442
* @retval config change any field whose default is not suitable
444
virtual void updateConfig(ClientTestConfig &config) const = 0;
447
* @param configName a unique string: the predefined names known by
448
* ClientTest::getTestData() are already used for the initial
449
* set of Evolution sync sources, for new sync sources
450
* build a string by combining them with the sync source name
451
* (e.g., "sqlite_vcard30")
452
* @param testCaseName a string recognized by ClientTest::getTestData() or an
453
* empty string if there are no predefined test cases
455
RegisterSyncSourceTest(const string &configName,
456
const string &testCaseName);
457
virtual ~RegisterSyncSourceTest() {}
459
const string m_configName;
460
const string m_testCaseName;
463
class TestRegistry : public vector<const RegisterSyncSourceTest *>
466
// TODO: using const RegisterSyncSourceTest * operator [] (int);
467
const RegisterSyncSourceTest * operator [] (const string &configName) const {
468
BOOST_FOREACH(const RegisterSyncSourceTest *test, *this) {
469
if (test->m_configName == configName) {
473
throw out_of_range(string("test config registry: ") + configName);
479
* a container for Synthesis XML config fragments
481
* Backends can define their own field lists, profiles, datatypes and
482
* remote rules. The name of each of these entities have to be unique:
483
* either prefix each name with the name of the backend or coordinate
484
* with other developers (e.g. regarding shared field lists).
486
* To add new items, add them to the respective hash in your backend's
487
* getDatastoreXML() or getSynthesisInfo() implementation. Both
488
* methods have default implementations: getSynthesisInfo() is called
489
* by the default getDatastoreXML() to provide some details and
490
* provides them based on the "type" configuration option.
492
* The default config XML contains several predefined items:
493
* - field lists: contacts, calendar, Note, bookmarks
494
* - profiles: vCard, vCalendar, Note, vBookmark
495
* - datatypes: vCard21, vCard30, vCalendar10, iCalendar20,
496
* note10/11 (no difference except the versioning!),
498
* - remote rule: EVOLUTION
500
* These items do not appear in the hashes, so avoid picking the same
501
* names. The entries of each hash has to be a well-formed XML
502
* element, their keys the name encoded in each XML element.
504
struct XMLConfigFragments {
505
class mapping : public std::map<std::string, std::string> {
510
BOOST_FOREACH(const value_type &entry, *this) {
511
len += entry.second.size() + 1;
514
BOOST_FOREACH(const value_type &entry, *this) {
527
* abstract base class for SyncSource with some common functionality
530
* Used to implement and call that functionality in multiple derived
531
* classes, including situations where a derived class is derived from
532
* this base via different intermediate classes, therefore the
533
* need to keep it abstract.
535
class SyncSourceBase : public Logger {
537
virtual ~SyncSourceBase() {}
539
/** the unique name of the sync source (for example, "addressbook") */
540
virtual const char *getName() const { return "uninitialized SyncSourceBase"; }
543
* Convenience function, to be called inside a catch() block of
544
* (or for) the sync source.
546
* Rethrows the exception to determine what it is, then logs it
547
* as an error and returns a suitable error code (usually a general
548
* STATUS_DATASTORE_FAILURE).
550
SyncMLStatus handleException();
553
* throw an exception after an operation failed
555
* output format: <source name>: <action>: <error string>
557
* @param action a string describing the operation or object involved
558
* @param error the errno error code for the failure
560
void throwError(const string &action, int error);
563
* throw an exception after an operation failed and
564
* remember that this instance has failed
566
* output format: <source name>: <failure>
568
* @param action a string describing what was attempted *and* how it failed
570
void throwError(const string &failure);
573
* The Synthesis engine only counts items which are deleted by the
574
* peer. Items deleted locally at the start of a
575
* refresh-from-server sync are not counted (and cannot be counted
578
* Sync sources which want to have those items included in the
579
* sync statistics should count *all* deleted items using these
580
* methods. SyncContext will use this number for
581
* refresh-from-server syncs.
584
virtual long getNumDeleted() const = 0;
585
virtual void setNumDeleted(long num) = 0;
586
virtual void incrementNumDeleted() = 0;
590
* Return Synthesis <datastore> XML fragment for this sync source.
591
* Must *not* include the <datastore> element; it is created by
594
* The default implementation returns a configuration for the
595
* SynthesisDBPlugin, which invokes SyncSource::Operations. Items
596
* are exchanged with the SyncsSource in the format defined by
597
* getSynthesisInfo(). The format used with the SyncML side is
598
* negotiated via the peer's capabilities, with the type defined
599
* in the configuration being the preferred one of the data store.
601
* See SyncContext::getConfigXML() for details about
602
* predefined <datatype> entries that can be referenced here.
604
* @retval xml put content of <datastore>...</datastore> here
605
* @retval fragments the necessary definitions for the datastore have to be added here
607
virtual void getDatastoreXML(string &xml, XMLConfigFragments &fragments);
610
* Synthesis <datatype> name which matches the format used
611
* for importing and exporting items (exportData()).
612
* This is not necessarily the same format that is given
613
* to the Synthesis engine. If this internal format doesn't
614
* have a <datatype> in the engine, then an empty string is
617
virtual string getNativeDatatypeName();
620
* Logging utility code.
622
* Every sync source adds "<name>" as prefix to its output.
623
* All calls are redirected into SyncContext logger.
625
virtual void messagev(Level level,
629
const char *function,
634
* return Synthesis API pointer, if one currently is available
635
* (between SyncEvolution_Module_CreateContext() and
636
* SyncEvolution_Module_DeleteContext())
638
virtual SDKInterface *getSynthesisAPI() const = 0;
641
* Prepare the sync source for usage inside a SyncML server. To
642
* be called directly after creating the source, if at all.
644
virtual void enableServerMode() = 0;
645
virtual bool serverModeEnabled() const = 0;
648
struct SynthesisInfo {
650
* name to use for MAKE/PARSETEXTWITHPROFILE,
651
* leave empty when acessing the field list directly
653
std::string m_profile;
656
* the second parameter for MAKE/PARSETEXTWITHPROFILE
657
* which specifies a remote rule to be applied when
658
* converting to and from the backend
660
std::string m_backendRule;
662
/** list of supported datatypes in "<use .../>" format */
663
std::string m_datatypes;
665
/** native datatype (see getNativeDatatypeName()) */
666
std::string m_native;
668
/** name of the field list used by the datatypes */
669
std::string m_fieldlist;
672
* One or more Synthesis script statements, separated
673
* and terminated with a semicolon. Can be left empty.
675
* If not empty, then these statements are executed directly
676
* before converting the current item fields into
677
* a single string with MAKETEXTWITHPROFILE() in the sync source's
678
* <beforewritescript> (see SyncSourceBase::getDatastoreXML()).
680
* This value is currently only used by sync sources which
683
std::string m_beforeWriteScript;
686
* Same as m_beforeWriteScript, but used directly after
687
* converting a string into fields with PARSETEXTWITHPROFILE()
688
* in <afterreadscript>.
690
std::string m_afterReadScript;
694
* helper function for getDatastoreXML(): fill in information
697
* @retval fragments the necessary definitions for the other
698
* return values have to be added here
700
virtual void getSynthesisInfo(SynthesisInfo &info,
701
XMLConfigFragments &fragments) = 0;
704
* utility code: creates Synthesis <use datatype=...>
705
* statements, using the predefined vCard21/vCard30/vcalendar10/icalendar20
706
* types. Throws an error if no suitable result can be returned (empty or invalid type)
708
* @param type the format specifier as used in SyncEvolution configs, with and without version
709
* (text/x-vcard:2.1, text/x-vcard, text/x-vcalendar, text/calendar, text/plain, ...);
710
* see SourceType::m_format
711
* @param forceFormat if true, then don't allow alternative formats (like vCard 3.0 in addition to 2.1);
712
* see SourceType::m_force
713
* @return generated XML fragment
715
std::string getDataTypeSupport(const std::string &type,
720
* SyncEvolution accesses all sources through this interface.
722
* Certain functionality is optional or can be implemented in
723
* different ways. These methods are accessed through functors
724
* (function objects) which may be unset. The expected usage is that
725
* derived classes fill in the pieces that they provide by binding the
726
* functors to normal methods. For example, TrackingSyncSource
727
* provides a normal base class with pure virtual functions which have
728
* to be provided by users of that class.
730
* Error reporting is done via the Log class.
732
class SyncSource : virtual public SyncSourceBase, public SyncSourceConfig, public SyncSourceReport
735
SyncSource(const SyncSourceParams ¶ms) :
736
SyncSourceConfig(params.m_name, params.m_nodes),
738
m_forceSlowSync(false)
741
virtual ~SyncSource() {}
744
* SyncSource implementations must register themselves here via
747
static SourceRegistry &getSourceRegistry();
750
* SyncSource tests are registered here by the constructor of
751
* RegisterSyncSourceTest
753
static TestRegistry &getTestRegistry();
756
Database(const string &name, const string &uri, bool isDefault = false) :
757
m_name( name ), m_uri( uri ), m_isDefault(isDefault) {}
762
typedef vector<Database> Databases;
765
* returns a list of all know data sources for the kind of items
766
* supported by this sync source
768
virtual Databases getDatabases() = 0;
771
* Actually opens the data source specified in the constructor,
772
* will throw the normal exceptions if that fails. Should
773
* not modify the state of the sync source.
775
* The expectation is that this call is fairly light-weight, but
776
* does enough checking to determine whether the source is
777
* usable. More expensive operations (like determining changes)
778
* should be done in the m_startDataRead callback (bound to
779
* beginSync() in some of the utility classes).
781
* In clients, it will be called for all sources before
782
* the sync starts. In servers, it is called for each source once
783
* the client asks for it, but not sooner.
785
virtual void open() = 0;
788
* The optional operations.
790
* All of them are guaranteed to happen between open() and
793
* They are all allowed to throw exceptions: the operations called
794
* by SyncEvolution then abort whatever SyncEvolution was doing
795
* and end in the normal exception handling. For the Synthesis
796
* operations, the bridge code in SynthesisDBPlugin code catches
797
* exceptions, logs them and translates them into Synthesis error
798
* codes, which are returned to the Synthesis engine.
802
* The caller determines where item data is stored (m_dirname)
803
* and where meta information about them (m_node). The callee
804
* then can use both arbitrarily. As an additional hint,
805
* m_mode specifies why and when the backup is made, which
806
* is useful to determine whether information can be reused.
810
BACKUP_BEFORE, /**< directly at start of sync */
811
BACKUP_AFTER, /**< directly after sync */
815
boost::shared_ptr<ConfigNode> m_node;
817
BackupInfo(Mode mode,
818
const string &dirname,
819
const boost::shared_ptr<ConfigNode> &node) :
825
struct ConstBackupInfo {
826
BackupInfo::Mode m_mode;
828
boost::shared_ptr<const ConfigNode> m_node;
830
ConstBackupInfo(BackupInfo::Mode mode,
831
const string &dirname,
832
const boost::shared_ptr<const ConfigNode> &node) :
840
* Dump all data from source unmodified into the given backup location.
841
* Information about the created backup is added to the
844
* Required for the backup/restore functionality in
845
* SyncEvolution, not for syncing itself. But typically it is
846
* called before syncing (can be turned off by users), so
847
* implementations can reuse the information gathered while
848
* making a backup in later operations.
850
* @param previous the most recent backup, empty m_dirname if none
851
* @param next the backup which is to be created, directory and node are empty
852
* @param report to be filled with information about backup (number of items, etc.)
854
typedef void (BackupData_t)(const ConstBackupInfo &oldBackup,
855
const BackupInfo &newBackup,
856
BackupReport &report);
857
boost::function<BackupData_t> m_backupData;
860
* Restore database from data stored in backupData().
861
* If possible don't touch items which are the same as in the
862
* backup, to mimimize impact on future incremental syncs.
864
* @param oldBackup the backup which is to be restored
865
* @param dryrun pretend to restore and fill in report, without
866
* actually touching backend data
867
* @param report to be filled with information about restore
868
* (number of total items and changes)
870
typedef void (RestoreData_t)(const ConstBackupInfo &oldBackup,
872
SyncSourceReport &report);
873
boost::function<RestoreData_t> m_restoreData;
876
* initialize information about local changes and items
877
* as in beginSync() with all parameters set to true,
878
* but without changing the state of the underlying database
880
* This method will be called to check for local changes without
881
* actually running a sync, so there is no matching end call.
883
* There might be sources which don't support non-destructive
884
* change tracking (in other words, checking changes permanently
885
* modifies the state of the source and cannot be repeated).
886
* Such sources should leave the functor empty.
888
typedef void (CheckStatus_t)(SyncSourceReport &local);
889
boost::function<CheckStatus_t> m_checkStatus;
892
* A quick check whether the source currently has data.
894
* If this cannot be determined easily, don't provide the
895
* operation. The information is currently only used to
896
* determine whether a slow sync should be allowed. If
897
* the operation is not provided, the assumption is that
898
* there is local data, which disables the "allow slow
899
* sync for empty databases" heuristic and forces the user
902
typedef bool (IsEmpty_t)();
903
boost::function<IsEmpty_t> m_isEmpty;
906
* Synthesis DB API callbacks. For documentation see the
907
* Synthesis API specification (PDF and/or sync_dbapi.h).
909
* Implementing this is necessary for SyncSources which want
910
* to be part of a sync session.
913
typedef void (Callback_t)();
914
typedef boost::function<Callback_t> CallbackFunctor_t;
915
typedef std::list<CallbackFunctor_t> Callbacks_t;
917
/** all of these functions will be called before accessing
918
the source's data for the first time, i.e., before m_startDataRead */
919
Callbacks_t m_startAccess;
921
typedef sysync::TSyError (StartDataRead_t)(const char *lastToken, const char *resumeToken);
922
boost::function<StartDataRead_t> m_startDataRead;
924
/** all of these functions will be called directly after
925
m_startDataRead() returned successfully */
926
Callbacks_t m_startSession;
928
typedef sysync::TSyError (EndDataRead_t)();
929
boost::function<EndDataRead_t> m_endDataRead;
931
typedef sysync::TSyError (StartDataWrite_t)();
932
boost::function<StartDataWrite_t> m_startDataWrite;
934
/** all of these functions will be called right
935
before m_endDataWrite() */
936
std::list<CallbackFunctor_t> m_endSession;
938
typedef sysync::TSyError (EndDataWrite_t)(bool success, char **newToken);
939
boost::function<EndDataWrite_t> m_endDataWrite;
941
/** the SynthesisDBPlugin is configured so that this operation
942
doesn't have to (and cannot) return the item data */
943
typedef sysync::TSyError (ReadNextItem_t)(sysync::ItemID aID,
944
sysync::sInt32 *aStatus, bool aFirst);
945
boost::function<ReadNextItem_t> m_readNextItem;
947
typedef sysync::TSyError (ReadItemAsKey_t)(sysync::cItemID aID, sysync::KeyH aItemKey);
948
boost::function<ReadItemAsKey_t> m_readItemAsKey;
950
typedef sysync::TSyError (InsertItemAsKey_t)(sysync::KeyH aItemKey, sysync::ItemID newID);
951
boost::function<InsertItemAsKey_t> m_insertItemAsKey;
953
typedef sysync::TSyError (UpdateItemAsKey_t)(sysync::KeyH aItemKey, sysync::cItemID aID, sysync::ItemID updID);
954
boost::function<UpdateItemAsKey_t> m_updateItemAsKey;
956
typedef sysync::TSyError (DeleteItem_t)(sysync::cItemID aID);
957
boost::function<DeleteItem_t> m_deleteItem;
962
* Synthesis administration callbacks. For documentation see the
963
* Synthesis API specification (PDF and/or sync_dbapi.h).
965
* Implementing this is *optional* in clients. In the Synthesis client
966
* engine, the "binfiles" module provides these calls without SyncEvolution
969
* In the Synthesis server engine, the
970
* SyncSource::enableServerMode() call must install an
971
* implementation, like the one from SyncSourceAdmin.
974
typedef sysync::TSyError (LoadAdminData_t)(const char *aLocDB,
977
boost::function<LoadAdminData_t> m_loadAdminData;
979
typedef sysync::TSyError (SaveAdminData_t)(const char *adminData);
980
boost::function<SaveAdminData_t> m_saveAdminData;
982
typedef bool (ReadNextMapItem_t)(sysync::MapID mID, bool aFirst);
983
boost::function<ReadNextMapItem_t> m_readNextMapItem;
985
typedef sysync::TSyError (InsertMapItem_t)(sysync::cMapID mID);
986
boost::function<InsertMapItem_t> m_insertMapItem;
988
typedef sysync::TSyError (UpdateMapItem_t)(sysync::cMapID mID);
989
boost::function<UpdateMapItem_t> m_updateMapItem;
991
typedef sysync::TSyError (DeleteMapItem_t)(sysync::cMapID mID);
992
boost::function<DeleteMapItem_t> m_deleteMapItem;
994
typedef sysync::TSyError (ReadBlob_t)(sysync::cItemID aID, const char *aBlobID,
995
void **aBlkPtr, size_t *aBlkSize,
997
bool aFirst, bool *aLast);
998
boost::function<ReadBlob_t> m_readBlob;
1000
typedef sysync::TSyError (WriteBlob_t)(sysync::cItemID aID, const char *aBlobID,
1001
void *aBlkPtr, size_t aBlkSize,
1003
bool aFirst, bool aLast);
1004
boost::function<WriteBlob_t> m_writeBlob;
1006
typedef sysync::TSyError (DeleteBlob_t)(sysync::cItemID aID, const char *aBlobID);
1007
boost::function<DeleteBlob_t> m_deleteBlob;
1010
const Operations &getOperations() { return m_operations; }
1013
* outside users of the source are only allowed to add callbacks,
1014
* not overwrite arbitrary operations
1016
void addCallback(Operations::CallbackFunctor_t callback, Operations::Callbacks_t Operations::* where) { (m_operations.*where).push_back(callback); }
1019
* closes the data source so that it can be reopened
1021
* Just as open() it should not affect the state of
1022
* the database unless some previous action requires
1025
virtual void close() = 0;
1028
* return Synthesis API pointer, if one currently is available
1029
* (between SyncEvolution_Module_CreateContext() and
1030
* SyncEvolution_Module_DeleteContext())
1032
virtual SDKInterface *getSynthesisAPI() const;
1035
* change the Synthesis API that is used by the source
1037
void pushSynthesisAPI(sysync::SDK_InterfaceType *synthesisAPI);
1040
* remove latest Synthesis API and return to previous one (if any)
1042
void popSynthesisAPI();
1045
* factory function for a SyncSource that provides the
1046
* source type specified in the params.m_nodes.m_configNode
1048
* @param error throw a runtime error describing what the problem is if no matching source is found
1049
* @param config optional, needed for intantiating virtual sources
1050
* @return valid instance, NULL if no source can handle the given type (only when error==false)
1052
static SyncSource *createSource(const SyncSourceParams ¶ms,
1054
SyncConfig *config = NULL);
1057
* Factory function for a SyncSource with the given name
1058
* and handling the kind of data specified by "type" (e.g.
1059
* "Evolution Contacts:text/x-vcard").
1061
* The source is instantiated with dummy configuration nodes under
1062
* the pseudo server name "testing". This function is used for
1063
* testing sync sources, not for real syncs. If the prefix is set,
1064
* then <prefix>_<name>_1 is used as database, just as in the
1065
* Client::Sync and Client::Source tests. Otherwise the default
1068
* @param error throw a runtime error describing what the problem is if no matching source is found
1069
* @return NULL if no source can handle the given type
1071
static SyncSource *createTestingSource(const string &name, const string &type, bool error,
1072
const char *prefix = getenv("CLIENT_TEST_EVOLUTION_PREFIX"));
1075
* Some information about available backends.
1076
* Multiple lines, formatted for users of the
1079
static string backendsInfo();
1081
* Debug information about backends.
1083
static string backendsDebug();
1086
* Mime type a backend communicates with the remote peer by default,
1087
* this is used to alert the remote peer in SAN during server alerted sync.
1089
virtual const char *getPeerMimeType() const =0;
1091
/* implementation of SyncSourceBase */
1092
virtual const char * getName() const { return SyncSourceConfig::getName(); }
1093
virtual long getNumDeleted() const { return m_numDeleted; }
1094
virtual void setNumDeleted(long num) { m_numDeleted = num; }
1095
virtual void incrementNumDeleted() { m_numDeleted++; }
1098
* Set to true in SyncContext::initSAN() when a SyncML server has
1099
* to force a client into slow sync mode. This is necessary because
1100
* the server cannot request that mode (missing in the standard).
1101
* Forcing the slow sync mode is done via a FORCESLOWSYNC() macro
1102
* call in an <alertscript>.
1104
void setForceSlowSync(bool forceSlowSync) { m_forceSlowSync = forceSlowSync; }
1105
bool getForceSlowSync() const { return m_forceSlowSync; }
1108
Operations m_operations;
1112
* Counter for items deleted in the source. Has to be incremented
1113
* by RemoveAllItems() and DeleteItem(). This counter is used to
1114
* update the Synthesis engine counter in those cases where the
1115
* engine does not (refresh from server) or cannot
1116
* (RemoveAllItems()) count the removals itself.
1120
bool m_forceSlowSync;
1123
* Interface pointer for this sync source, allocated for us by the
1124
* Synthesis engine and registered here by
1125
* SyncEvolution_Module_CreateContext(). Only valid until
1126
* SyncEvolution_Module_DeleteContext(), in other words, while
1127
* the engine is running.
1129
std::vector<sysync::SDK_InterfaceType *> m_synthesisAPI;
1133
* A SyncSource with no pure virtual functions.
1135
class DummySyncSource : public SyncSource
1138
DummySyncSource(const SyncSourceParams ¶ms) :
1139
SyncSource(params) {}
1141
DummySyncSource(const std::string &name) :
1142
SyncSource(SyncSourceParams(name)) {}
1144
virtual Databases getDatabases() { return Databases(); }
1145
virtual void open() {}
1146
virtual void close() {}
1147
virtual void getSynthesisInfo(SynthesisInfo &info,
1148
XMLConfigFragments &fragments) {}
1149
virtual void enableServerMode() {}
1150
virtual bool serverModeEnabled() const { return false; }
1151
virtual const char *getPeerMimeType() const {return "";}
1155
* A special source which combines one or more real sources.
1156
* Most of the special handling for that is in SyncContext.cpp.
1158
* This class can be instantiated, opened and closed if and only if
1159
* the underlying sources also support that.
1161
class VirtualSyncSource : public DummySyncSource
1163
std::vector< boost::shared_ptr<SyncSource> > m_sources;
1167
* @param config optional: when given, the constructor will instantiate the
1168
* referenced underlying sources and check them in open()
1170
VirtualSyncSource(const SyncSourceParams ¶ms, SyncConfig *config = NULL);
1172
/** opens underlying sources and checks config by calling getDataTypeSupport() */
1173
virtual void open();
1174
virtual void close();
1177
* returns array with source names that are referenced by this
1180
std::vector<std::string> getMappedSources();
1183
* returns <use datatype=...> statements for XML config,
1184
* throws error if not configured correctly
1186
std::string getDataTypeSupport();
1187
using SyncSourceBase::getDataTypeSupport;
1191
* If any of the sub datasource has no databases associated, return an empty
1192
* database list to indicate a possibly error condition; otherwise return a
1193
* dummy database to identify "calendar+todo" combined datasource.
1195
virtual Databases getDatabases();
1199
* Hooks up the Synthesis DB Interface start sync (BeginDataRead) and
1200
* end sync (EndDataWrite) calls with virtual methods. Ensures that
1201
* sleepSinceModification() is called.
1203
* Inherit from this class in your sync source and call the init()
1206
class SyncSourceSession : virtual public SyncSourceBase {
1209
* called before Synthesis engine starts to ask for changes and item data
1211
* See BeingDataRead for details.
1213
* @param lastToken identifies the last completed sync
1214
* @param resumeToken identifies a more recent sync which needs to be resumed;
1215
* if not empty, then report changes made after that sync
1216
* instead of the last completed sync
1218
virtual void beginSync(const std::string &lastToken, const std::string &resumeToken) = 0;
1221
* called after completing or suspending the current sync
1223
* See EndDataWrite for details.
1225
* @return a token identifying this sync session for a future beginSync()
1227
virtual std::string endSync(bool success) = 0;
1229
/** set Synthesis DB Interface operations */
1230
void init(SyncSource::Operations &ops);
1232
sysync::TSyError startDataRead(const char *lastToken, const char *resumeToken);
1233
sysync::TSyError endDataWrite(bool success, char **newToken);
1238
* Implements the Synthesis DB Interface for reporting item changes
1239
* (ReadNextItemAsKey) *without* actually delivering the item data.
1241
class SyncSourceChanges : virtual public SyncSourceBase {
1243
SyncSourceChanges();
1254
* Add the LUID of a NEW/UPDATED/DELETED item.
1255
* If unspecified, the luid is added to the list of
1256
* all items. This must be done *in addition* to adding
1257
* the luid with a specific state.
1259
* For example, the luid of an updated item should be added with
1260
* addItem(luid [, ANY]) and again with addItem(luid, DELETED).
1262
* The Synthesis engine does not need the list of deleted items
1263
* and does not distinguish between added and updated items, so
1264
* for syncing, adding DELETED items is optional and all items
1265
* which are different from the last sync can be added as
1266
* UPDATED. The client-test program expects that the information
1267
* is provided precisely.
1269
* @return true if the luid was already listed
1271
bool addItem(const string &luid, State state = ANY);
1273
typedef std::set<std::string> Items_t;
1274
const Items_t &getItems(State state) { return m_items[state]; }
1275
const Items_t &getAllItems() const { return m_items[ANY]; }
1276
const Items_t &getNewItems() const { return m_items[NEW]; }
1277
const Items_t &getUpdatedItems() const { return m_items[UPDATED]; }
1278
const Items_t &getDeletedItems() const { return m_items[DELETED]; }
1280
/** set Synthesis DB Interface operations */
1281
void init(SyncSource::Operations &ops);
1284
Items_t m_items[MAX];
1286
Items_t::const_iterator m_it;
1288
sysync::TSyError iterate(sysync::ItemID aID,
1289
sysync::sInt32 *aStatus,
1294
* Implements the Synthesis DB Interface for deleting an item
1295
* (DeleteItem). Increments number of deleted items in
1298
class SyncSourceDelete : virtual public SyncSourceBase {
1300
virtual void deleteItem(const string &luid) = 0;
1302
/** set Synthesis DB Interface operations */
1303
void init(SyncSource::Operations &ops);
1306
sysync::TSyError deleteItemSynthesis(sysync::cItemID aID);
1310
* an interface for reading and writing items in the internal
1311
* format; see SyncSourceSerialize for an explanation
1313
class SyncSourceRaw : virtual public SyncSourceBase {
1315
class InsertItemResult {
1317
InsertItemResult() :
1322
* @param luid the LUID after the operation; during an update the LUID must
1323
* not be changed, so return the original one here
1324
* @param revision the revision string after the operation; leave empty if not used
1325
* @param merged set this to true if an existing item was updated instead of adding it
1327
InsertItemResult(const string &luid,
1328
const string &revision,
1331
m_revision(revision),
1340
/** same as SyncSourceSerialize::insertItem(), but with internal format */
1341
virtual InsertItemResult insertItemRaw(const std::string &luid, const std::string &item) = 0;
1343
/** same as SyncSourceSerialize::readItem(), but with internal format */
1344
virtual void readItemRaw(const std::string &luid, std::string &item) = 0;
1348
* Implements the Synthesis DB Interface for importing/exporting item
1349
* data (ReadItemAsKey, InsertItemAsKey, UpdateItemAsKey) in such a
1350
* way that the sync source only has to deal with a text
1351
* representation of an item.
1353
* There may be two such representations:
1354
* - "engine format" is the one exchanged with the Synthesis engine
1355
* - "internal or raw format" is a format that might better capture
1356
* the internal representation and can be used for backup/restore
1359
* To give an example, the EvolutionMemoSource uses plain text as
1360
* engine format and iCalendar 2.0 as raw format.
1362
* The BackupData_t and RestoreData_t operations are implemented by
1363
* this class using the internal format.
1365
* The engine format must be something that the Synthesis engine can
1366
* parse and generate, in other words, there must be a corresponding
1367
* profile in the XML configuration. This class uses information
1368
* provided by the sync source (mime type and version) and from the
1369
* configuration (format selected by user) to generate the required
1370
* XML configuration parts for common configurations (vCard,
1371
* vCalendar, iCalendar, text). Special representations can be added
1372
* to the global XML configuration by overriding default
1373
* implementations provided in this class.
1375
* InsertItemAsKey and UpdateItemAsKey are mapped to the same
1376
* insertItem() call because in practice it can happen that a request
1377
* to add an item must be turned into an update. For example, a
1378
* meeting was imported both into the server and the client. A request
1379
* to add the item again should be treated as an update, based on the
1380
* unique iCalendar 2.0 LUID.
1382
class SyncSourceSerialize : virtual public SyncSourceBase, virtual public SyncSourceRaw {
1385
* Returns the preferred mime type of the items handled by the sync source.
1386
* Example: "text/x-vcard"
1388
virtual const char *getMimeType() const = 0;
1391
* Returns the version of the mime type used by client.
1394
virtual const char *getMimeVersion() const = 0;
1397
* returns the backend selection and configuration
1399
virtual SourceType getSourceType() const = 0;
1402
* Create or modify an item.
1404
* The sync source should be flexible: if the LUID is non-empty, it
1405
* shall modify the item referenced by the LUID. If the LUID is
1406
* empty, the normal operation is to add it. But if the item
1407
* already exists (e.g., a calendar event which was imported
1408
* by the user manually), then the existing item should be
1409
* updated also in the second case.
1411
* Passing a LUID of an item which does not exist is an error.
1412
* This error should be reported instead of covering it up by
1413
* (re)creating the item.
1415
* Errors are signaled by throwing an exception. Returning empty
1416
* strings in the result is an error which triggers an "item could
1417
* not be stored" error.
1419
* @param luid identifies the item to be modified, empty for creating
1420
* @param item contains the new content of the item, using the engine format
1421
* @return the result of inserting the item
1423
virtual InsertItemResult insertItem(const std::string &luid, const std::string &item) = 0;
1426
* Return item data in engine format.
1428
* @param luid identifies the item
1429
* @retval item item data
1431
virtual void readItem(const std::string &luid, std::string &item) = 0;
1433
/* implement SyncSourceRaw under the assumption that the internal and engine format are identical */
1434
virtual InsertItemResult insertItemRaw(const std::string &luid, const std::string &item) { return insertItem(luid, item); }
1435
virtual void readItemRaw(const std::string &luid, std::string &item) { return readItem(luid, item); }
1437
/** set Synthesis DB Interface operations */
1438
void init(SyncSource::Operations &ops);
1442
* used getMimeType(), getMimeVersion() and getSourceType()
1443
* to provide the information necessary for automatic
1444
* conversion to the sync source's internal item representation
1446
virtual void getSynthesisInfo(SynthesisInfo &info,
1447
XMLConfigFragments &fragments);
1449
sysync::TSyError readItemAsKey(sysync::cItemID aID, sysync::KeyH aItemKey);
1450
sysync::TSyError insertItemAsKey(sysync::KeyH aItemKey, sysync::cItemID aID, sysync::ItemID newID);
1454
* Implements change tracking based on a "revision" string, a string
1455
* which is guaranteed to change automatically each time an item is
1456
* modified. Backup/restore is optionally implemented by this class if
1457
* pointers to SyncSourceRaw and SyncSourceDelete interfaces are
1458
* passed to init(). For backup only the former is needed, for restore
1461
* Potential implementations of the revision string are:
1462
* - a modification time stamp
1463
* - a hash value of a textual representation of the item
1464
* (beware, such a hash might change as the textual representation
1465
* changes even though the item is unchanged)
1467
* Sync sources which want to use this functionality have to provide
1468
* the following functionality by implementing the pure virtual
1470
* - enumerate all existing items
1471
* - provide LUID and the revision string
1472
* The LUID must remain *constant* when making changes to an item,
1473
* whereas the revision string must *change* each time the item is
1474
* changed by anyone.
1475
* Both can be arbitrary strings, but keeping them simple (printable
1476
* ASCII, no white spaces, no equal sign) makes debugging simpler
1477
* because they can be stored as they are as key/value pairs in the
1478
* sync source's change tracking config node (the .other.ini files when
1479
* using file-based configuration). More complex strings use escape
1480
* sequences introduced with an exclamation mark for unsafe characters.
1482
* Most of the functionality of this class must be activated
1483
* explicitly as part of the life cycle of the sync source instance by
1484
* calling detectChanges(), updateRevision() and deleteRevision().
1486
* If the required interfaces are provided to init(), then backup/restore
1487
* operations are set. init() also hooks into the session life cycle
1488
* with an end callback that ensures that enough time passes at the end
1489
* of the sync. This is important for sync sources which use time stamps
1490
* as revision string. "enough time" is defined by a parameter to the
1493
class SyncSourceRevisions : virtual public SyncSourceChanges, virtual public SyncSourceBase {
1495
typedef map<string, string> RevisionMap_t;
1498
* fills the complete mapping from UID to revision string of all
1499
* currently existing items
1501
* Usually both UID and revision string must be non-empty. The
1502
* only exception is a refresh-from-client: in that case the
1503
* revision string may be empty. The implementor of this call
1504
* cannot know whether empty strings are allowed, therefore it
1505
* should not throw errors when it cannot create a non-empty
1506
* string. The caller of this method will detect situations where
1507
* a non-empty string is necessary and none was provided.
1509
* This call is typically only invoked only once during the
1510
* lifetime of a source. The result returned in that invocation is
1511
* used throught the session.
1513
virtual void listAllItems(RevisionMap_t &revisions) = 0;
1516
* calculate changes, call when sync source is ready for
1517
* listAllItems() and before changes are needed
1519
* The trackingNode must be provided by the caller. It will
1520
* be updated by each of the calls and must be stored by
1523
* @param trackingNode a config node for exclusive use by this class
1525
void detectChanges(ConfigNode &trackingNode);
1528
* record that an item was added or updated
1530
* @param old_luid empty for add, old LUID otherwise
1531
* @param new_luid normally LUIDs must not change, but this call allows it
1532
* @param revision revision string after change
1534
void updateRevision(ConfigNode &trackingNode,
1535
const std::string &old_luid,
1536
const std::string &new_luid,
1537
const std::string &revision);
1540
* record that we deleted an item
1542
* @param luid the obsolete LUID
1544
void deleteRevision(ConfigNode &trackingNode,
1545
const std::string &luid);
1548
* set Synthesis DB Interface and backup/restore operations
1549
* @param raw needed for backups; if NULL, no backups are made
1550
* @param del needed for restores; if NULL, only backups are possible
1551
* @param granularity time that has to pass between making a modification
1552
* and checking for changes; this class ensures that
1553
* at least this amount of time has passed before letting
1554
* the session terminate. Delays in different source do
1557
void init(SyncSourceRaw *raw, SyncSourceDelete *del,
1559
SyncSource::Operations &ops);
1562
SyncSourceRaw *m_raw;
1563
SyncSourceDelete *m_del;
1564
int m_revisionAccuracySeconds;
1566
/** buffers the result of the initial listAllItems() call */
1567
RevisionMap_t m_revisions;
1568
bool m_revisionsSet;
1569
void initRevisions();
1572
* Dump all data from source unmodified into the given directory.
1573
* The ConfigNode can be used to store meta information needed for
1574
* restoring that state. Both directory and node are empty.
1576
void backupData(const SyncSource::Operations::ConstBackupInfo &oldBackup,
1577
const SyncSource::Operations::BackupInfo &newBackup,
1578
BackupReport &report);
1581
* Restore database from data stored in backupData(). Will be
1582
* called inside open()/close() pair. beginSync() is *not* called.
1584
void restoreData(const SyncSource::Operations::ConstBackupInfo &oldBackup,
1586
SyncSourceReport &report);
1589
* Increments the time stamp of the latest database modification,
1590
* called automatically whenever revisions change.
1592
void databaseModified();
1594
/** time stamp of latest database modification, for sleepSinceModification() */
1595
time_t m_modTimeStamp;
1596
void sleepSinceModification();
1601
* Common logging for sync sources.
1603
* This class wraps the Synthesis DB functors that were set before
1604
* calling its init() method. The wrappers then log a single line
1605
* describing what is happening (adding/updating/removing)
1606
* to which item (with a short item specific description extracted
1607
* from the incoming item data or the backend).
1609
class SyncSourceLogging : public virtual SyncSourceBase
1613
* wrap Synthesis DB Interface operations
1615
* @param fields list of fields to read in getDescription()
1616
* @param sep separator between non-empty fields
1618
void init(const std::list<std::string> &fields,
1619
const std::string &sep,
1620
SyncSource::Operations &ops);
1623
* Extract short description from Synthesis item data.
1624
* The default implementation reads a list of fields
1625
* as strings and concatenates the non-empty ones
1628
* @param aItemKey key for reading fields
1629
* @return description, empty string will cause the ID of the item to be printed
1631
virtual std::string getDescription(sysync::KeyH aItemKey);
1634
* Extract short description from backend.
1635
* Necessary for deleted items. The default implementation
1636
* returns an empty string, so that implementing this
1639
* @param luid LUID of the item to be deleted in the backend
1640
* @return description, empty string will cause the ID of the item to be printed
1642
virtual std::string getDescription(const string &luid);
1645
std::list<std::string> m_fields;
1648
sysync::TSyError insertItemAsKey(sysync::KeyH aItemKey, sysync::ItemID newID,
1649
const boost::function<SyncSource::Operations::InsertItemAsKey_t> &parent);
1650
sysync::TSyError updateItemAsKey(sysync::KeyH aItemKey, sysync::cItemID aID, sysync::ItemID newID,
1651
const boost::function<SyncSource::Operations::UpdateItemAsKey_t> &parent);
1652
sysync::TSyError deleteItem(sysync::cItemID aID,
1653
const boost::function<SyncSource::Operations::DeleteItem_t> &parent);
1657
* Implements Load/SaveAdminData and MapItem handling in a SyncML
1658
* server. Uses a single property for the admin data in the "internal"
1659
* node and a complete node for the map items.
1661
class SyncSourceAdmin : public virtual SyncSourceBase
1663
boost::shared_ptr<ConfigNode> m_configNode;
1664
std::string m_adminPropertyName;
1665
boost::shared_ptr<ConfigNode> m_mappingNode;
1666
bool m_mappingLoaded;
1668
ConfigProps m_mapping;
1669
ConfigProps::const_iterator m_mappingIterator;
1671
sysync::TSyError loadAdminData(const char *aLocDB,
1674
sysync::TSyError saveAdminData(const char *adminData);
1675
bool readNextMapItem(sysync::MapID mID, bool aFirst);
1676
sysync::TSyError insertMapItem(sysync::cMapID mID);
1677
sysync::TSyError updateMapItem(sysync::cMapID mID);
1678
sysync::TSyError deleteMapItem(sysync::cMapID mID);
1682
void mapid2entry(sysync::cMapID mID, string &key, string &value);
1683
void entry2mapid(const string &key, const string &value, sysync::MapID mID);
1686
/** flexible initialization */
1687
void init(SyncSource::Operations &ops,
1688
const boost::shared_ptr<ConfigNode> &config,
1689
const std::string adminPropertyName,
1690
const boost::shared_ptr<ConfigNode> &mapping);
1693
* simpler initialization, using the default placement of data
1694
* inside the SyncSourceConfig base class
1696
void init(SyncSource::Operations &ops, SyncSource *source);
1700
* Implements Read/Write/DeleteBlob. Blobs are stored inside a
1701
* configurable directory, which has to be unique for the current
1704
class SyncSourceBlob : public virtual SyncSourceBase
1707
* Only one blob is active at a time.
1708
* This utility class provides the actual implementation.
1710
sysync::TBlob m_blob;
1712
sysync::TSyError readBlob(sysync::cItemID aID, const char *aBlobID,
1713
void **aBlkPtr, size_t *aBlkSize,
1715
bool aFirst, bool *aLast) {
1716
return m_blob.ReadBlob(aID, aBlobID, aBlkPtr, aBlkSize, aTotSize, aFirst, aLast);
1718
sysync::TSyError writeBlob(sysync::cItemID aID, const char *aBlobID,
1719
void *aBlkPtr, size_t aBlkSize,
1721
bool aFirst, bool aLast) {
1722
mkdir_p(m_blob.getBlobPath());
1723
return m_blob.WriteBlob(aID, aBlobID, aBlkPtr, aBlkSize, aTotSize, aFirst, aLast);
1725
sysync::TSyError deleteBlob(sysync::cItemID aID, const char *aBlobID) {
1726
return m_blob.DeleteBlob(aID, aBlobID);
1729
sysync::TSyError loadAdminData(sysync::cItemID aID, const char *aBlobID,
1730
void **aBlkPtr, size_t *aBlkSize, size_t *aTotSize,
1731
bool aFirst, bool *aLast);
1734
void init(SyncSource::Operations &ops,
1735
const std::string &dir);
1740
* This is an interface definition that is expected by the client-test
1741
* program. Part of the reason for this requirement is that the test
1742
* program was originally written for the Funambol SyncSource API.
1743
* The other reason is that the testing is based on importing/exporting
1744
* items in the internal format of the sync source, which has to be
1745
* text based or even MIMEDIR based (for tests involving synccompare).
1747
class TestingSyncSource : public SyncSource,
1748
virtual public SyncSourceSession,
1749
virtual public SyncSourceChanges,
1750
virtual public SyncSourceDelete,
1751
virtual public SyncSourceSerialize {
1753
TestingSyncSource(const SyncSourceParams ¶ms) :
1756
SyncSourceSession::init(m_operations);
1757
SyncSourceChanges::init(m_operations);
1758
SyncSourceDelete::init(m_operations);
1759
SyncSourceSerialize::init(m_operations);
1761
~TestingSyncSource() {}
1763
virtual SourceType getSourceType() const { return SyncSourceConfig::getSourceType(); }
1765
void removeAllItems() {
1766
BOOST_FOREACH(const string &luid, getAllItems()) {
1774
#endif // INCL_SYNCSOURCE
added
removed
.pc/0001-patch-from-Patrick-Ohly-convert-explicitly-between-s.patch/src/syncevo/SyncSource.h
