src/parser.h

   1 ///
   2 /// \file       parser.h
   3 ///             Virtual parser wrapper
   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_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 { class Data; }
  32
  33 namespace Barry {
  34
  35 // also acts as a null parser
  36 //
  37 // Parser class
  38 //
  39 /// Base class for the parser hierarchy.  If in debug mode, this
  40 /// class can be used as a null parser.  Call Init() and the protocol
  41 /// will be dumped to stdout and no parsing will be done.
  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 class BXEXPORT Parser
  49 {
  50 public:
  51         Parser() {}
  52         virtual ~Parser() {}
  53
  54         /// Reset and prepare for a new raw data packet
  55         virtual void Clear() {}
  56
  57         /// Stores the IDs
  58         virtual void SetIds(uint8_t RecType, uint32_t UniqueId) {}
  59
  60         /// Called to parse the header portion of the raw data packet.
  61         /// data contains the entire packet, and offset contains the
  62         /// location at which to start parsing.
  63         virtual void ParseHeader(const Data &data, size_t &offset) {}
  64
  65         /// Called to parse sub fields in the raw data packet.
  66         /// The same data is passed as was passed in ParseHeader,
  67         /// only the offset will be updated if it was advanced during
  68         /// the header parsing.
  69         virtual void ParseFields(const Data &data, size_t &offset) {}
  70
  71         /// Called at the very end of record parsing, and used to
  72         /// store the final packet somewhere, either in memory, disk, etc.
  73         virtual void Store() {}
  74 };
  75
  76
  77 //
  78 // RecordParser template class
  79 //
  80 /// Template class for easy creation of specific parser objects.  This template
  81 /// takes the following template arguments:
  82 ///
  83 ///     - RecordT: One of the record parser classes in record.h
  84 ///     - StorageT: A custom storage functor class.  An object of this type
  85 ///             will be called as a function with parsed Record as an
  86 ///             argument.  This happens on the fly as the data is retrieved
  87 ///             from the device over USB, so it should not block forever.
  88 ///
  89 /// Example LoadDatabase() call:
  90 ///
  91 /// <pre>
  92 /// struct StoreContact
  93 /// {
  94 ///     std::vector<Contact> &amp;array;
  95 ///     StoreContact(std::vector<Contact> &amp;a) : array(a) {}
  96 ///     void operator() (const Contact &amp;c)
  97 ///     {
  98 ///         array.push_back(c);
  99 ///     }
 100 /// };
 101 ///
 102 /// Controller con(probeResult);
 103 /// con.OpenMode(Controller::Desktop);
 104 /// std::vector<Contact> contactList;
 105 /// StoreContact storage(contactList);
 106 /// RecordParser<Contact, StoreContact> parser(storage);
 107 /// con.LoadDatabase(con.GetDBID("Address Book"), parser);
 108 /// </pre>
 109 ///
 110 template <class RecordT, class StorageT>
 111 class RecordParser : public Parser
 112 {
 113         StorageT *m_store;
 114         bool m_owned;
 115         RecordT m_rec;
 116
 117 public:
 118         /// Constructor that references an externally managed storage object.
 119         RecordParser(StorageT &storage)
 120                 : m_store(&storage), m_owned(false) {}
 121
 122         /// Constructor that references a locally managed storage object.
 123         /// The pointer passed in will be stored, and freed when this class
 124         /// is destroyed.  It is safe to call this constructor with
 125         /// a 'new'ly created storage object.
 126         RecordParser(StorageT *storage)
 127                 : m_store(storage), m_owned(true) {}
 128
 129         ~RecordParser()
 130         {
 131                 if( this->m_owned )
 132                         delete m_store;
 133         }
 134
 135         virtual void Clear()
 136         {
 137                 m_rec = RecordT();
 138         }
 139
 140         virtual void SetIds(uint8_t RecType, uint32_t UniqueId)
 141         {
 142                 m_rec.SetIds(RecType, UniqueId);
 143         }
 144
 145         virtual void ParseHeader(const Data &data, size_t &offset)
 146         {
 147                 m_rec.ParseHeader(data, offset);
 148         }
 149
 150         virtual void ParseFields(const Data &data, size_t &offset)
 151         {
 152                 m_rec.ParseFields(data, offset);
 153         }
 154
 155         virtual void Store()
 156         {
 157                 (*m_store)(m_rec);
 158         }
 159 };
 160
 161 } // namespace Barry
 162
 163 #endif
 164