src/parser.h

   1 ///
   2 /// \file       parser.h
   3 ///             Virtual parser wrapper
   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_PARSER_H__
  23 #define __BARRY_PARSER_H__
  24
  25 #include "dll.h"
  26 #include "data.h"
  27 #include "protocol.h"
  28 #include <stdint.h>             // for uint32_t
  29
  30 // forward declarations
  31 namespace Barry {
  32         class Data;
  33         class IConverter;
  34 }
  35
  36 namespace Barry {
  37
  38 //
  39 // Parser class
  40 //
  41 /// Base class for the parser hierarchy.
  42 ///
  43 /// This class provides the interface that the Controller class uses
  44 /// to pass raw data it reads from the device.  The Controller, along
  45 /// with the Packet class, calls each of the virtual functions below
  46 /// in the same order.
  47 ///
  48 /// This class is kept as a pure abstract class, in order to make sure
  49 /// that the compiler will catch any API changes, for code derived
  50 /// from it.
  51 ///
  52 class BXEXPORT Parser
  53 {
  54 public:
  55         Parser() {}
  56         virtual ~Parser() {}
  57
  58         /// Reset and prepare for a new raw data packet
  59         virtual void Clear() = 0;
  60
  61         /// Stores the IDs
  62         virtual void SetIds(const std::string &DbName,
  63                 uint8_t RecType, uint32_t UniqueId) = 0;
  64
  65         /// Called to parse the header portion of the raw data packet.
  66         /// data contains the entire packet, and offset contains the
  67         /// location at which to start parsing.
  68         virtual void ParseHeader(const Data &data, size_t &offset) = 0;
  69
  70         /// Called to parse sub fields in the raw data packet.
  71         /// The same data is passed as was passed in ParseHeader,
  72         /// only the offset will be updated if it was advanced during
  73         /// the header parsing.
  74         virtual void ParseFields(const Data &data, size_t &offset,
  75                 const IConverter *ic) = 0;
  76
  77         /// Called at the very end of record parsing, and used to
  78         /// store the final packet somewhere, either in memory, disk, etc.
  79         virtual void Store() = 0;
  80 };
  81
  82
  83 //
  84 // NullParser class
  85 //
  86 /// If in debug mode, this class can be used as a null parser.
  87 /// Call Init() and the protocol will be dumped to stdout and
  88 /// no parsing will be done.
  89 ///
  90 /// Do NOT derive your own personal parser classes from this,
  91 /// unless you are perfectly confident that you will catch
  92 /// future API changes on the devel tree without the compiler's
  93 /// help.
  94 ///
  95 class BXEXPORT NullParser : public Parser
  96 {
  97 public:
  98         NullParser() {}
  99         virtual ~NullParser() {}
 100
 101         /// Reset and prepare for a new raw data packet
 102         virtual void Clear() {}
 103
 104         /// Stores the IDs
 105         virtual void SetIds(const std::string &DbName,
 106                 uint8_t RecType, uint32_t UniqueId) {}
 107
 108         /// Called to parse the header portion of the raw data packet.
 109         /// data contains the entire packet, and offset contains the
 110         /// location at which to start parsing.
 111         virtual void ParseHeader(const Data &data, size_t &offset) {}
 112
 113         /// Called to parse sub fields in the raw data packet.
 114         /// The same data is passed as was passed in ParseHeader,
 115         /// only the offset will be updated if it was advanced during
 116         /// the header parsing.
 117         virtual void ParseFields(const Data &data, size_t &offset,
 118                 const IConverter *ic) {}
 119
 120         /// Called at the very end of record parsing, and used to
 121         /// store the final packet somewhere, either in memory, disk, etc.
 122         virtual void Store() {}
 123 };
 124
 125
 126 //
 127 // RecordParser template class
 128 //
 129 /// Template class for easy creation of specific parser objects.  This template
 130 /// takes the following template arguments:
 131 ///
 132 ///     - RecordT: One of the record parser classes in record.h
 133 ///     - StorageT: A custom storage functor class.  An object of this type
 134 ///             will be called as a function with parsed Record as an
 135 ///             argument.  This happens on the fly as the data is retrieved
 136 ///             from the device over USB, so it should not block forever.
 137 ///
 138 /// Example LoadDatabase() call:
 139 ///
 140 /// <pre>
 141 /// struct StoreContact
 142 /// {
 143 ///     std::vector<Contact> &amp;array;
 144 ///     StoreContact(std::vector<Contact> &amp;a) : array(a) {}
 145 ///     void operator() (const Contact &amp;c)
 146 ///     {
 147 ///         array.push_back(c);
 148 ///     }
 149 /// };
 150 ///
 151 /// Controller con(probeResult);
 152 /// con.OpenMode(Controller::Desktop);
 153 /// std::vector<Contact> contactList;
 154 /// StoreContact storage(contactList);
 155 /// RecordParser<Contact, StoreContact> parser(storage);
 156 /// con.LoadDatabase(con.GetDBID("Address Book"), parser);
 157 /// </pre>
 158 ///
 159 template <class RecordT, class StorageT>
 160 class RecordParser : public Parser
 161 {
 162         StorageT *m_store;
 163         bool m_owned;
 164         RecordT m_rec;
 165
 166 public:
 167         /// Constructor that references an externally managed storage object.
 168         RecordParser(StorageT &storage)
 169                 : m_store(&storage), m_owned(false) {}
 170
 171         /// Constructor that references a locally managed storage object.
 172         /// The pointer passed in will be stored, and freed when this class
 173         /// is destroyed.  It is safe to call this constructor with
 174         /// a 'new'ly created storage object.
 175         RecordParser(StorageT *storage)
 176                 : m_store(storage), m_owned(true) {}
 177
 178         ~RecordParser()
 179         {
 180                 if( this->m_owned )
 181                         delete m_store;
 182         }
 183
 184         virtual StorageT* GetStore()
 185         {
 186                 return m_store;
 187         }
 188
 189         virtual const StorageT* GetStore() const
 190         {
 191                 return m_store;
 192         }
 193
 194         virtual void Clear()
 195         {
 196                 m_rec = RecordT();
 197         }
 198
 199         virtual void SetIds(const std::string &DbName,
 200                                 uint8_t RecType, uint32_t UniqueId)
 201         {
 202                 m_rec.SetIds(RecType, UniqueId);
 203         }
 204
 205         virtual void ParseHeader(const Data &data, size_t &offset)
 206         {
 207                 m_rec.ParseHeader(data, offset);
 208         }
 209
 210         virtual void ParseFields(const Data &data, size_t &offset,
 211                                  const IConverter *ic)
 212         {
 213                 m_rec.ParseFields(data, offset, ic);
 214         }
 215
 216         virtual void Store()
 217         {
 218                 (*m_store)(m_rec);
 219         }
 220 };
 221
 222 } // namespace Barry
 223
 224 #endif
 225