src/controller.h

   1 ///
   2 /// \file       controller.h
   3 ///             High level BlackBerry API class
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2008, 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_CONTROLLER_H__
  23 #define __BARRY_CONTROLLER_H__
  24
  25 #include "dll.h"
  26 #include "usbwrap.h"
  27 #include "probe.h"
  28 #include "socket.h"
  29 #include "record.h"
  30 #include "data.h"
  31
  32 /// Project namespace, containing all related functions and classes.
  33 /// This is the only namespace applications should be concerned with,
  34 /// for now.
  35 namespace Barry {
  36
  37 // forward declarations
  38 class Parser;
  39 class Builder;
  40 class DBPacket;
  41
  42 //
  43 // Controller class
  44 //
  45 /// The main interface class.  This class coordinates the communication to
  46 /// a single handheld.
  47 ///
  48 /// To use this class, use the following steps:
  49 ///
  50 ///     - Probe the USB bus for matching devices with the Probe class
  51 ///     - Pass one of the probe results into the Controller constructor
  52 ///             to connect
  53 ///     - Call OpenMode() to select the desired mode.  This will fill all
  54 ///             internal data structures for that mode, such as the
  55 ///             Database Database in Desktop mode.
  56 ///             NOTE: only Desktop mode is currently implemented.
  57 ///     - Call GetDBDB() to get the device's database database
  58 ///     - Call GetDBID() to get a database ID by name
  59 ///     - In Desktop mode, call LoadDatabase() to retrieve and store a database
  60 ///
  61 class BXEXPORT Controller
  62 {
  63         friend class Barry::DBPacket;
  64
  65 public:
  66         /// Handheld mode type
  67         enum ModeType {
  68                 Unspecified,            //< default on start up
  69                 Bypass,                 //< unsupported, unknown
  70                 Desktop,                //< desktop mode required for database
  71                                         //< operation
  72                 JavaLoader,             //< unsupported
  73                 UsbSerData              //< GPRS modem support over USB
  74         };
  75         enum CommandType { Unknown, DatabaseAccess };
  76
  77 private:
  78         Usb::Device m_dev;
  79         Usb::Interface *m_iface;
  80         uint32_t m_pin;
  81
  82         Socket m_socket;
  83
  84         CommandTable m_commandTable;
  85         DatabaseDatabase m_dbdb;
  86
  87         ModeType m_mode;
  88
  89         uint16_t m_modeSocket;                  // socket recommended by device
  90                                                 // when mode was selected
  91
  92         // UsbSerData cache
  93         Data m_writeCache, m_readCache;
  94
  95         // tracking of open Desktop socket, and the need to reset
  96         bool m_halfOpen;
  97
  98 protected:
  99         void SelectMode(ModeType mode);
 100         unsigned int GetCommand(CommandType ct);
 101
 102         void LoadCommandTable();
 103         void LoadDBDB();
 104
 105 public:
 106         Controller(const ProbeResult &device);
 107         ~Controller();
 108
 109         //////////////////////////////////
 110         // meta access
 111
 112         /// Returns DatabaseDatabase object for this connection.
 113         /// Must call OpenMode() to select Desktop mode first
 114         const DatabaseDatabase& GetDBDB() const { return m_dbdb; }
 115         unsigned int GetDBID(const std::string &name) const;
 116
 117         //////////////////////////////////
 118         // general operations
 119         void OpenMode(ModeType mode, const char *password = 0);
 120         void RetryPassword(const char *password);
 121
 122         //////////////////////////////////
 123         // Desktop mode - database specific
 124
 125         // dirty flag related functions, for sync operations
 126         void GetRecordStateTable(unsigned int dbId, RecordStateTable &result);
 127         void AddRecord(unsigned int dbId, Builder &build); // RecordId is
 128                 // retrieved from build, and duplicate IDs are allowed,
 129                 // but *not* recommended!
 130         void GetRecord(unsigned int dbId, unsigned int stateTableIndex, Parser &parser);
 131         void SetRecord(unsigned int dbId, unsigned int stateTableIndex, Builder &build);
 132         void ClearDirty(unsigned int dbId, unsigned int stateTableIndex);
 133         void DeleteRecord(unsigned int dbId, unsigned int stateTableIndex);
 134
 135         // pure load/save operations
 136         void LoadDatabase(unsigned int dbId, Parser &parser);
 137         void SaveDatabase(unsigned int dbId, Builder &builder);
 138
 139         template <class RecordT, class StorageT> void LoadDatabaseByType(StorageT &store);
 140         template <class RecordT, class StorageT> void SaveDatabaseByType(StorageT &store);
 141
 142         template <class StorageT> void LoadDatabaseByName(const std::string &name, StorageT &store);
 143         template <class StorageT> void SaveDatabaseByName(const std::string &name, StorageT &store);
 144
 145         template <class RecordT> void AddRecordByType(uint32_t recordId, const RecordT &rec);
 146
 147
 148         //////////////////////////////////
 149         // UsbSerData mode - modem specific
 150
 151         void SerialRead(Data &data, int timeout); // can be called from separate thread
 152         void SerialWrite(const Data &data);
 153 };
 154
 155 } // namespace Barry
 156
 157 #endif
 158