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-2013, 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 Evolution3;
 191         class Google;
 192         class KDEPim;
 193         class Unsupported;
 194 }
 195
 196 //
 197 // Converter
 198 //
 199 /// Base class for the converter api, which converts from/to a data-holding
 200 /// plugin configuration class to/from the API.
 201 ///
 202 /// For 0.22, it will manually write the config fields into a std::string
 203 /// suitable for a call to API::SetConfiguration(), and then call
 204 /// SetConfiguration() itself.
 205 ///
 206 /// For 0.4x, it may do the same thing, or might use the new 0.4x calls
 207 /// to set the individual fields through the low level opensync API.
 208 ///
 209 /// The API class creates an instance of a matching derived class
 210 /// (for 0.22 or 0.4x, per the API itself), and returns a pointer
 211 /// whenever asked.
 212 ///
 213 class Converter
 214 {
 215 public:
 216         typedef std::tr1::shared_ptr<OpenSync::Config::Plugin> plugin_ptr;
 217
 218 public:
 219         virtual ~Converter() {}
 220
 221         virtual bool IsPluginSupported(const std::string &plugin_name,
 222                 std::string *appname = 0) const = 0;
 223         virtual plugin_ptr CreateAndLoadPlugin(const Member &member) = 0;
 224
 225         virtual std::string GetPluginName(const Config::Barry &) const = 0;
 226         virtual std::string GetPluginName(const Config::Evolution &) const = 0;
 227         virtual std::string GetPluginName(const Config::Evolution3 &) const = 0;
 228         virtual std::string GetPluginName(const Config::Google &) const = 0;
 229         virtual std::string GetPluginName(const Config::KDEPim &) const = 0;
 230         virtual std::string GetPluginName(const Config::Unsupported &) const = 0;
 231
 232         virtual bool IsConfigured(const Config::Barry &) const = 0;
 233         virtual bool IsConfigured(const Config::Evolution &) const = 0;
 234         virtual bool IsConfigured(const Config::Evolution3 &) const = 0;
 235         virtual bool IsConfigured(const Config::Google &) const = 0;
 236         virtual bool IsConfigured(const Config::KDEPim &) const = 0;
 237         virtual bool IsConfigured(const Config::Unsupported &) const = 0;
 238
 239         virtual Config::pst_type GetSupportedSyncTypes(const Config::Barry &) const = 0;
 240         virtual Config::pst_type GetSupportedSyncTypes(const Config::Evolution &) const = 0;
 241         virtual Config::pst_type GetSupportedSyncTypes(const Config::Evolution3 &) const = 0;
 242         virtual Config::pst_type GetSupportedSyncTypes(const Config::Google &) const = 0;
 243         virtual Config::pst_type GetSupportedSyncTypes(const Config::KDEPim &) const = 0;
 244         virtual Config::pst_type GetSupportedSyncTypes(const Config::Unsupported &) const = 0;
 245
 246         virtual void Load(Config::Barry &config, const Member &member) = 0;
 247         virtual void Load(Config::Evolution &config, const Member &member) = 0;
 248         virtual void Load(Config::Evolution3 &config, const Member &member) = 0;
 249         virtual void Load(Config::Google &config, const Member &member) = 0;
 250         virtual void Load(Config::KDEPim &config, const Member &member) = 0;
 251         virtual void Load(Config::Unsupported &config, const Member &member) = 0;
 252
 253         virtual void Save(const Config::Barry &config,
 254                                 const std::string &group_name) = 0;
 255         virtual void Save(const Config::Evolution &config,
 256                                 const std::string &group_name) = 0;
 257         virtual void Save(const Config::Evolution3 &config,
 258                                 const std::string &group_name) = 0;
 259         virtual void Save(const Config::Google &config,
 260                                 const std::string &group_name) = 0;
 261         virtual void Save(const Config::KDEPim &config,
 262                                 const std::string &group_name) = 0;
 263         virtual void Save(const Config::Unsupported &config,
 264                                 const std::string &group_name) = 0;
 265 };
 266
 267 class API
 268 {
 269 public:
 270         API()
 271         {
 272         }
 273
 274         virtual ~API()
 275         {
 276         }
 277
 278         // Functional abilities information... this does not come from
 279         // the engine itself, but is information the osbase library
 280         // determines useful for applications to know
 281         virtual bool IsSlowSyncSupported() const = 0;
 282
 283         // General engine information
 284         virtual const char* GetVersion() const = 0;
 285         virtual const char* GetEngineName() const = 0; // "0.22" or "0.40", etc
 286         virtual void GetPluginNames(string_list_type &plugins) = 0;
 287         virtual void GetFormats(format_list_type &formats) = 0;
 288
 289         // Information about configured groups
 290         virtual void GetGroupNames(string_list_type &groups) = 0;
 291         virtual void GetMembers(const std::string &group_name,
 292                 member_list_type &members) = 0;
 293
 294         // Group configuration
 295         virtual void AddGroup(const std::string &group_name) = 0;
 296         virtual void DeleteGroup(const std::string &group_name) = 0;
 297
 298         // Plugin configuration helper
 299         virtual Converter& GetConverter() = 0;
 300
 301         // Member configuration
 302         // AddMember() returns new member_id?
 303         virtual long AddMember(const std::string &group_name,
 304                 const std::string &plugin_name,
 305                 const std::string &member_name) = 0;
 306         virtual bool IsConfigurable(const std::string &group_name,
 307                 long member_id) = 0;
 308         virtual std::string GetConfiguration(const std::string &group_name,
 309                 long member_id) = 0;
 310         virtual void SetConfiguration(const std::string &group_name,
 311                 long member_id, const std::string &config_data) = 0;
 312         virtual void Discover(const std::string &group_name) = 0;
 313
 314         // Syncing
 315         //
 316         // API Note: we put the sync_types here, and not in a special
 317         // API of its own, since 0.22 does not save this state, and
 318         // while 0.4x does, it is not easy to determine whether every
 319         // member in the group is configured the same... so we do it on
 320         // the fly during the sync process, and we don't save the state.
 321         //
 322         // Therefore it is possible that you can disable an objtype in
 323         // a 0.4x config, and sync here with it enabled, and the config
 324         // files will remain the same!  This could be confusing for debugging,
 325         // make sure you compare the barry config with the opensync config
 326         // when debugging sync issues.
 327         //
 328         virtual void Sync(const std::string &group_name,
 329                 SyncStatus &status_callback,
 330                 Config::pst_type sync_types/* = PST_DO_NOT_SET*/) = 0;
 331 };
 332
 333 class APISet : private std::vector<API*>
 334 {
 335         typedef std::vector<API*>               base_type;
 336
 337 public:
 338         APISet();
 339         ~APISet();
 340
 341         void OpenAll();         // throws if not all can be opened
 342         int OpenAvailable();    // opens only what is available and
 343                                 // returns # of APIs successfully loaded.
 344                                 // throws if some already loaded
 345
 346         int GetAvailable() const;// returns # of APIs successfully loaded
 347
 348         API* os40();
 349         API* os22();
 350 };
 351
 352 } // namespace OpenSync
 353
 354 #endif
 355