src/m_desktop.h

   1 ///
   2 /// \file       m_desktop.h
   3 ///             Mode class for the Desktop mode
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2010, Net Direct Inc. (http://www.netdirect.ca/)
   8
   9     This program is free software; you can redistribute it and/or modify
  10     it under the terms of the GNU General Public License as published by
  11     the Free Software Foundation; either version 2 of the License, or
  12     (at your option) any later version.
  13
  14     This program is distributed in the hope that it will be useful,
  15     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  17
  18     See the GNU General Public License in the COPYING file at the
  19     root directory of this project for more details.
  20 */
  21
  22 #ifndef __BARRY_M_DESKTOP_H__
  23 #define __BARRY_M_DESKTOP_H__
  24
  25 #include "dll.h"
  26 #include "m_mode_base.h"
  27 #include "data.h"
  28 #include "socket.h"
  29 #include "record.h"
  30 #include "builder.h"
  31
  32 namespace Barry {
  33
  34 // forward declarations
  35 class Parser;
  36 class IConverter;
  37
  38 namespace Mode {
  39
  40 class DBLoader;
  41
  42 //
  43 // Desktop class
  44 //
  45 /// The main interface class to the device databases.
  46 ///
  47 /// To use this class, use the following steps:
  48 ///
  49 ///     - Create a Controller object (see Controller class for more details)
  50 ///     - Create this Mode::Desktop object, passing in the Controller
  51 ///             object during construction
  52 ///     - Call Open() to open database socket and finish constructing.
  53 ///     - Call GetDBDB() to get the device's database database
  54 ///     - Call GetDBID() to get a database ID by name
  55 ///     - Call LoadDatabase() to retrieve and store a database
  56 ///
  57 class BXEXPORT Desktop : public Mode
  58 {
  59         friend class DBLoader;
  60
  61 public:
  62         enum CommandType { Unknown, DatabaseAccess };
  63
  64 private:
  65         // packet data
  66         Data m_command, m_response;
  67
  68         CommandTable m_commandTable;
  69         DatabaseDatabase m_dbdb;
  70
  71         // external objects (optional, can be null)
  72         const IConverter *m_ic;
  73
  74 protected:
  75         void LoadCommandTable();
  76         void LoadDBDB();
  77
  78         //////////////////////////////////
  79         // overrides
  80
  81         virtual void OnOpen();
  82
  83 public:
  84         Desktop(Controller &con);
  85         Desktop(Controller &con, const IConverter &ic);
  86         ~Desktop();
  87
  88         //////////////////////////////////
  89         // meta access
  90
  91         /// Returns DatabaseDatabase object for this connection.
  92         /// Must call Open() first, which loads the DBDB.
  93         const DatabaseDatabase& GetDBDB() const { return m_dbdb; }
  94         unsigned int GetDBID(const std::string &name) const;
  95         unsigned int GetDBCommand(CommandType ct);
  96
  97         void SetIConverter(const IConverter &ic);
  98
  99         //////////////////////////////////
 100         // Desktop mode - database specific
 101
 102         // dirty flag related functions, for sync operations
 103         void GetRecordStateTable(unsigned int dbId, RecordStateTable &result);
 104         void AddRecord(unsigned int dbId, Builder &build); // RecordId is
 105                 // retrieved from build, and duplicate IDs are allowed,
 106                 // but *not* recommended!
 107         void GetRecord(unsigned int dbId, unsigned int stateTableIndex, Parser &parser);
 108         void SetRecord(unsigned int dbId, unsigned int stateTableIndex, Builder &build);
 109         void ClearDirty(unsigned int dbId, unsigned int stateTableIndex);
 110         void DeleteRecord(unsigned int dbId, unsigned int stateTableIndex);
 111
 112         // pure load/save operations
 113         void LoadDatabase(unsigned int dbId, Parser &parser);
 114         void ClearDatabase(unsigned int dbId);
 115         void SaveDatabase(unsigned int dbId, Builder &builder);
 116
 117         template <class RecordT, class StorageT> void LoadDatabaseByType(StorageT &store);
 118         template <class RecordT, class StorageT> void SaveDatabaseByType(StorageT &store);
 119
 120         template <class StorageT> void LoadDatabaseByName(const std::string &name, StorageT &store);
 121         template <class StorageT> void SaveDatabaseByName(const std::string &name, StorageT &store);
 122
 123         template <class RecordT> void AddRecordByType(uint32_t recordId, const RecordT &rec);
 124
 125 };
 126
 127 // used to hold internal-only state
 128 struct DBLoaderData;
 129
 130 //
 131 // DBLoader
 132 //
 133 /// Database Loader operation class.  Encapsulates the load / save
 134 /// logic of Desktop::LoadDatabase() and someday Desktop::SaveDatabase()
 135 /// in such a way that the loading of individual records is
 136 /// controllable by the user, instead of using the parser callback mechanism.
 137 ///
 138 /// This class can be reused to load / save multiple databases, but
 139 /// do not call Desktop members while a load operation is in progress.
 140 ///
 141 class BXEXPORT DBLoader
 142 {
 143         Desktop &m_desktop;
 144         Data m_send;
 145         bool m_loading;
 146         std::string m_dbName;
 147         DBLoaderData *m_loader;
 148
 149 public:
 150         explicit DBLoader(Desktop &desktop);
 151         ~DBLoader();
 152
 153         /// Do not call Desktop members if this is true.
 154         bool IsBusy() const { return m_loading; }
 155
 156         // caller-controllable load/save operations... if
 157         // these functions return true, then new data has
 158         // just been loaded into the data object passed to
 159         // the constructor
 160         //
 161         // Both of these functions use a DBData object in order
 162         // to pass buffers from application code all the way down
 163         // to the socket level, to avoid copies wherever possible.
 164         bool StartDBLoad(unsigned int dbId, DBData &data);
 165         bool GetNextRecord(DBData &data);
 166 };
 167
 168 } // namespace Barry::Mode
 169
 170
 171
 172
 173
 174 //
 175 // DeviceBuilder
 176 //
 177 /// Takes a list of database dbId's and behaves like a Builder,
 178 /// trying to avoid copies where possible on the device loading end.
 179 ///
 180 class BXEXPORT DeviceBuilder : public Builder
 181 {
 182         typedef unsigned int                            dbid_type;
 183
 184         struct DBLabel
 185         {
 186                 dbid_type id;
 187                 std::string name;
 188
 189                 DBLabel(dbid_type id, const std::string &name)
 190                         : id(id)
 191                         , name(name)
 192                 {
 193                 }
 194         };
 195
 196         typedef std::vector<DBLabel>                    list_type;
 197
 198         // list of databases to fetch during build
 199         list_type m_dbIds;
 200         list_type::iterator m_current;
 201
 202         Mode::Desktop &m_desktop;
 203
 204         // loader object to use optimized batch loading while
 205         // giving per-record control
 206         Mode::DBLoader m_loader;
 207
 208 public:
 209         explicit DeviceBuilder(Mode::Desktop &desktop);
 210
 211         // searches the dbdb from the desktop to find the dbId,
 212         // returns false if not found, and adds it to the list of
 213         // databases to retrieve if found
 214         bool Add(const std::string &dbname);
 215
 216         /// sets the internal iterator to the start of the list
 217         /// in order to perform a fresh run
 218         void Restart() { m_current = m_dbIds.begin(); }
 219
 220         //
 221         // Builder overrides
 222         //
 223
 224         // has both BuildRecord() and Retrieve() functionality,
 225         // and uses data all the way down to the socket level copy
 226         virtual bool BuildRecord(DBData &data, size_t &offset,
 227                 const IConverter *ic);
 228         virtual bool FetchRecord(DBData &data, const IConverter *ic);
 229         virtual bool EndOfFile() const;
 230 };
 231
 232
 233 //
 234 // DeviceParser
 235 //
 236 /// A parser class that "parses" raw data into a device.  Basically this
 237 /// is a pipe-oriented way to call SaveDatabase().
 238 ///
 239 /// Note that this is a multi-record parser.  For each incoming DBData
 240 /// that has a new DBName, a new save will be started.  There is no
 241 /// way to filter out records, except via the callback, so the easiest
 242 /// way to filter out records by database name is on the Builder side.
 243 ///
 244 class BXEXPORT DeviceParser
 245 {
 246 public:
 247         enum WriteMode {
 248                 /// Similar to SaveDatabase().  Erases all records from
 249                 /// the existing database and then uploads all new records.
 250                 ERASE_ALL_WRITE_ALL,
 251
 252                 /// Adds any new records, and for records with Unique IDs
 253                 /// that already exist, overwrite them.
 254                 INDIVIDUAL_OVERWRITE,
 255
 256                 /// Adds any new records, but if a record exists with the
 257                 /// current Unique ID, skip that record and don't write it
 258                 /// to the device.
 259                 ADD_BUT_NO_OVERWRITE,
 260
 261                 /// Adds all incoming records as brand new records, generating
 262                 /// a new Unique ID for each one, and leaving any existing
 263                 /// records intact.
 264                 ADD_WITH_NEW_ID,
 265
 266                 /// Calls the virtual function DecideWrite(...) for each
 267                 /// record, passing in the data.  DecideWrite() returns one
 268                 /// of these WriteMode values.
 269                 DECIDE_BY_CALLBACK,
 270
 271                 /// Primarily used by DecideWrite(), and causes the current
 272                 /// record to not be written.
 273                 DROP_RECORD
 274         };
 275
 276 private:
 277         Mode::Desktop &m_desktop;
 278         WriteMode m_mode;
 279
 280         std::string m_current_db;
 281         unsigned int m_current_dbid;
 282         RecordStateTable m_rstate;
 283
 284 protected:
 285         void StartDB(const DBData &data, const IConverter *ic);
 286         void WriteNext(const DBData &data, const IConverter *ic);
 287
 288 public:
 289         DeviceParser(Mode::Desktop &desktop, WriteMode mode);
 290         virtual ~DeviceParser();
 291
 292         /// Callback... you must derive and override this if you use
 293         /// the DECIDE_BY_CALLBACK mode.
 294         /// May be called multiple times per record.
 295         virtual WriteMode DecideWrite(const DBData &record) const
 296         {
 297                 return DROP_RECORD;
 298         }
 299
 300         /// Parser overrides
 301         virtual void ParseRecord(const DBData &data, const IConverter *ic);
 302 };
 303
 304
 305 } // namespace Barry
 306
 307 #endif
 308