desktop/src/osbase.h

   1 ///
   2 /// \file       osbase.h
   3 ///             Base API class for OpenSync interaction.
   4 ///             This API will operate both 0.22 and 0.4x
   5 ///
   6
   7 /*
   8     Copyright (C) 2009-2012, Net Direct Inc. (http://www.netdirect.ca/)
   9
  10     This program is free software; you can redistribute it and/or modify
  11     it under the terms of the GNU General Public License as published by
  12     the Free Software Foundation; either version 2 of the License, or
  13     (at your option) any later version.
  14
  15     This program is distributed in the hope that it will be useful,
  16     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  18
  19     See the GNU General Public License in the COPYING file at the
  20     root directory of this project for more details.
  21 */
  22
  23 #ifndef __BARRYDESKTOP_OSBASE_H__
  24 #define __BARRYDESKTOP_OSBASE_H__
  25
  26 #include <vector>
  27 #include <string>
  28 #include <iosfwd>
  29 #include <tr1/memory>
  30 #include "ostypes.h"
  31
  32 namespace OpenSync {
  33
  34 struct Member
  35 {
  36         std::string group_name;
  37         long id;
  38         std::string friendly_name;      // may not always have a name
  39         std::string plugin_name;
  40 };
  41
  42 struct MemberSet : public std::vector<Member>
  43 {
  44         Member* Find(long id);
  45         Member* Find(const char *plugin_name);
  46         long FindId(const char *plugin_name); // returns -1 if not found
  47 };
  48
  49 struct Format
  50 {
  51         std::string name;
  52         std::string object_type;
  53 };
  54
  55 struct FormatSet : public std::vector<Format>
  56 {
  57         Format* Find(const char *name);
  58 };
  59
  60 typedef std::vector<std::string>                string_list_type;
  61 typedef MemberSet                               member_list_type;
  62 typedef FormatSet                               format_list_type;
  63
  64 std::ostream& operator<< (std::ostream &os, const string_list_type &list);
  65 std::ostream& operator<< (std::ostream &os, const Member &member);
  66 std::ostream& operator<< (std::ostream &os, const member_list_type &list);
  67 std::ostream& operator<< (std::ostream &os, const Format &format);
  68 std::ostream& operator<< (std::ostream &os, const format_list_type &list);
  69
  70
  71 class SyncConflictPrivateBase;
  72
  73 struct SyncChange
  74 {
  75         int id;
  76         long member_id;
  77         std::string plugin_name;
  78         std::string uid;
  79         std::string printable_data;
  80 };
  81
  82 class SyncConflict : public std::vector<SyncChange>
  83 {
  84         SyncConflictPrivateBase &m_conflict;
  85
  86 public:
  87         SyncConflict(SyncConflictPrivateBase &conflict);
  88         ~SyncConflict();
  89
  90         bool IsAbortSupported() const;
  91         bool IsIgnoreSupported() const;
  92         bool IsKeepNewerSupported() const;
  93
  94         std::string GetMenu() const;
  95         void Select(int change_id);  // takes the id field of SyncChange
  96         void Abort();
  97         void Duplicate();
  98         void Ignore();
  99         void KeepNewer();
 100
 101         std::ostream& Dump(std::ostream &os) const;
 102 };
 103
 104 inline std::ostream& operator<< (std::ostream &os, const SyncConflict &conflict)
 105 {
 106         return conflict.Dump(os);
 107 }
 108
 109
 110 class SyncSummaryPrivateBase;
 111
 112 struct SyncMemberSummary
 113 {
 114         int id;
 115         std::string objtype_name;
 116         long member_id;
 117         std::string plugin_name;
 118         unsigned long added;
 119         unsigned long modified;
 120         unsigned long deleted;
 121
 122         SyncMemberSummary()
 123                 : added(0), modified(0), deleted(0)
 124         {}
 125 };
 126
 127 class SyncSummary : public std::vector<SyncMemberSummary>
 128 {
 129         SyncSummaryPrivateBase &m_summary;
 130
 131 public:
 132         SyncSummary(SyncSummaryPrivateBase &summary);
 133         ~SyncSummary();
 134
 135         void Abort();
 136         void Continue();
 137
 138         std::ostream& Dump(std::ostream &os) const;
 139 };
 140
 141 inline std::ostream& operator<< (std::ostream &os, const SyncSummary &summary)
 142 {
 143         return summary.Dump(os);
 144 }
 145
 146
 147 // notes: OpenSync::SyncStatus is a base class with all the opensync
 148 // callbacks as virtual functions, with reasonable defaults.  The
 149 // programmer can override any callbacks he so chooses as below.
 150 //
 151 // If a callback has state or information or requires a decision, it
 152 // passes in a reference to a base class (example below: SyncConflict).
 153 // This base class is really a reference to a derived class specific
 154 // to the 0.22 or 0.4x library API, and contains pointers to the
 155 // OpenSync40 or OpenSync22 classes and private structs, and handles
 156 // all cleanup of the state it holds.  Also, these classes hold
 157 // information in C++ style variables... for example SyncConflict
 158 // will hold a vector of objects that contain the osync change
 159 // information of each conflicting change, as well as a means to
 160 // access a pretty printed version.  No OpenSync constants will
 161 // be used in these objects.
 162 //
 163 // If abstracted enough, the override code should be dead simple,
 164 // like below, and also be generic enough to run on both 0.22 and
 165 // 0.4x libraries, dynamically. :-D
 166 //
 167 class SyncStatus
 168 {
 169 public:
 170         virtual ~SyncStatus();
 171
 172         // virtual overrides
 173         virtual void HandleConflict(OpenSync::SyncConflict &conflict);
 174         virtual void EntryStatus(const std::string &msg, bool error);
 175         virtual void MappingStatus(const std::string &msg, bool error);
 176         virtual void EngineStatus(const std::string &msg, bool error, bool slowsync);
 177         virtual void MemberStatus(long member_id,
 178                 const std::string &plugin_name,
 179                 const std::string &msg, bool error);
 180         virtual void CheckSummary(OpenSync::SyncSummary &summary);
 181
 182         virtual void ReportError(const std::string &msg);
 183 };
 184
 185 // forward declarations for the Converter class
 186 namespace Config {
 187         class Plugin;
 188         class Barry;
 189         class Evolution;
 190         class Google;
 191         class KDEPim;
 192         class Unsupported;
 193 }
 194
 195 //
 196 // Converter
 197 //
 198 /// Base class for the converter api, which converts from/to a data-holding
 199 /// plugin configuration class to/from the API.
 200 ///
 201 /// For 0.22, it will manually write the config fields into a std::string
 202 /// suitable for a call to API::SetConfiguration(), and then call
 203 /// SetConfiguration() itself.
 204 ///
 205 /// For 0.4x, it may do the same thing, or might use the new 0.4x calls
 206 /// to set the individual fields through the low level opensync API.
 207 ///
 208 /// The API class creates an instance of a matching derived class
 209 /// (for 0.22 or 0.4x, per the API itself), and returns a pointer
 210 /// whenever asked.
 211 ///
 212 class Converter
 213 {
 214 public:
 215         typedef std::tr1::shared_ptr<OpenSync::Config::Plugin> plugin_ptr;
 216
 217 public:
 218         virtual ~Converter() {}
 219
 220         virtual bool IsPluginSupported(const std::string &plugin_name,
 221                 std::string *appname = 0) const = 0;
 222         virtual plugin_ptr CreateAndLoadPlugin(const Member &member) = 0;
 223
 224         virtual std::string GetPluginName(const Config::Barry &) const = 0;
 225         virtual std::string GetPluginName(const Config::Evolution &) const = 0;
 226         virtual std::string GetPluginName(const Config::Google &) const = 0;
 227         virtual std::string GetPluginName(const Config::KDEPim &) const = 0;
 228         virtual std::string GetPluginName(const Config::Unsupported &) const = 0;
 229
 230         virtual bool IsConfigured(const Config::Barry &) const = 0;
 231         virtual bool IsConfigured(const Config::Evolution &) const = 0;
 232         virtual bool IsConfigured(const Config::Google &) const = 0;
 233         virtual bool IsConfigured(const Config::KDEPim &) const = 0;
 234         virtual bool IsConfigured(const Config::Unsupported &) const = 0;
 235
 236         virtual Config::pst_type GetSupportedSyncTypes(const Config::Barry &) const = 0;
 237         virtual Config::pst_type GetSupportedSyncTypes(const Config::Evolution &) const = 0;
 238         virtual Config::pst_type GetSupportedSyncTypes(const Config::Google &) const = 0;
 239         virtual Config::pst_type GetSupportedSyncTypes(const Config::KDEPim &) const = 0;
 240         virtual Config::pst_type GetSupportedSyncTypes(const Config::Unsupported &) const = 0;
 241
 242         virtual void Load(Config::Barry &config, const Member &member) = 0;
 243         virtual void Load(Config::Evolution &config, const Member &member) = 0;
 244         virtual void Load(Config::Google &config, const Member &member) = 0;
 245         virtual void Load(Config::KDEPim &config, const Member &member) = 0;
 246         virtual void Load(Config::Unsupported &config, const Member &member) = 0;
 247
 248         virtual void Save(const Config::Barry &config,
 249                                 const std::string &group_name) = 0;
 250         virtual void Save(const Config::Evolution &config,
 251                                 const std::string &group_name) = 0;
 252         virtual void Save(const Config::Google &config,
 253                                 const std::string &group_name) = 0;
 254         virtual void Save(const Config::KDEPim &config,
 255                                 const std::string &group_name) = 0;
 256         virtual void Save(const Config::Unsupported &config,
 257                                 const std::string &group_name) = 0;
 258 };
 259
 260 class API
 261 {
 262 public:
 263         API()
 264         {
 265         }
 266
 267         virtual ~API()
 268         {
 269         }
 270
 271         // Functional abilities information... this does not come from
 272         // the engine itself, but is information the osbase library
 273         // determines useful for applications to know
 274         virtual bool IsSlowSyncSupported() const = 0;
 275
 276         // General engine information
 277         virtual const char* GetVersion() const = 0;
 278         virtual const char* GetEngineName() const = 0; // "0.22" or "0.40", etc
 279         virtual void GetPluginNames(string_list_type &plugins) = 0;
 280         virtual void GetFormats(format_list_type &formats) = 0;
 281
 282         // Information about configured groups
 283         virtual void GetGroupNames(string_list_type &groups) = 0;
 284         virtual void GetMembers(const std::string &group_name,
 285                 member_list_type &members) = 0;
 286
 287         // Group configuration
 288         virtual void AddGroup(const std::string &group_name) = 0;
 289         virtual void DeleteGroup(const std::string &group_name) = 0;
 290
 291         // Plugin configuration helper
 292         virtual Converter& GetConverter() = 0;
 293
 294         // Member configuration
 295         // AddMember() returns new member_id?
 296         virtual long AddMember(const std::string &group_name,
 297                 const std::string &plugin_name,
 298                 const std::string &member_name) = 0;
 299         virtual bool IsConfigurable(const std::string &group_name,
 300                 long member_id) = 0;
 301         virtual std::string GetConfiguration(const std::string &group_name,
 302                 long member_id) = 0;
 303         virtual void SetConfiguration(const std::string &group_name,
 304                 long member_id, const std::string &config_data) = 0;
 305         virtual void Discover(const std::string &group_name) = 0;
 306
 307         // Syncing
 308         //
 309         // API Note: we put the sync_types here, and not in a special
 310         // API of its own, since 0.22 does not save this state, and
 311         // while 0.4x does, it is not easy to determine whether every
 312         // member in the group is configured the same... so we do it on
 313         // the fly during the sync process, and we don't save the state.
 314         //
 315         // Therefore it is possible that you can disable an objtype in
 316         // a 0.4x config, and sync here with it enabled, and the config
 317         // files will remain the same!  This could be confusing for debugging,
 318         // make sure you compare the barry config with the opensync config
 319         // when debugging sync issues.
 320         //
 321         virtual void Sync(const std::string &group_name,
 322                 SyncStatus &status_callback,
 323                 Config::pst_type sync_types/* = PST_DO_NOT_SET*/) = 0;
 324 };
 325
 326 class APISet : private std::vector<API*>
 327 {
 328         typedef std::vector<API*>               base_type;
 329
 330 public:
 331         APISet();
 332         ~APISet();
 333
 334         void OpenAll();         // throws if not all can be opened
 335         int OpenAvailable();    // opens only what is available and
 336                                 // returns # of APIs successfully loaded.
 337                                 // throws if some already loaded
 338
 339         int GetAvailable() const;// returns # of APIs successfully loaded
 340
 341         API* os40();
 342         API* os22();
 343 };
 344
 345 } // namespace OpenSync
 346
 347 #endif
 348