src/builder.h

   1 ///
   2 /// \file       builder.h
   3 ///             Virtual protocol packet builder wrapper
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2009, 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_BUILDER_H__
  23 #define __BARRY_BUILDER_H__
  24
  25 #include "dll.h"
  26
  27 namespace Barry {
  28
  29 // forward declarations
  30 class IConverter;
  31
  32 //
  33 // Builder class
  34 //
  35 /// Base class for the builder functor hierarchy.
  36 ///
  37 /// This defines the API used by the Controller and Packet classes
  38 /// for building a raw device record to write to the device.
  39 ///
  40 class BXEXPORT Builder
  41 {
  42 public:
  43         Builder() {}
  44         virtual ~Builder() {}
  45
  46         /// Called first in the sequence, to allow the application to
  47         /// load the needed data from memory, disk, etc.  If successful,
  48         /// return true.  If at the end of the series, return false.
  49         virtual bool Retrieve(unsigned int databaseId) = 0;
  50
  51         /// Called to retrive the unique ID for this record.
  52         virtual uint8_t GetRecType() const = 0;
  53         virtual uint32_t GetUniqueId() const = 0;
  54
  55         /// Called before BuildFields() in order to build the header
  56         /// for this record.  Store the raw data in data, at the
  57         /// offset given in offset.  When finished, update offset to
  58         /// point to the next spot to put new data.
  59         virtual void BuildHeader(Data &data, size_t &offset) = 0;
  60
  61         /// Called to build the record field data.  Store the raw data
  62         /// in data, using offset to know where to write.  Be sure to
  63         /// update offset, and be sure to adjust the size of the data
  64         /// packet (possibly with Data::ReleaseBuffer()).
  65         virtual void BuildFields(Data &data, size_t &offset,
  66                 const IConverter *ic) = 0;
  67 };
  68
  69
  70 //
  71 // RecordBuilder template class
  72 //
  73 /// Template class for easy creation of specific protocol packet builder
  74 /// objects.  This template takes the following template arguments:
  75 ///
  76 ///     - RecordT: One of the record classes in record.h
  77 ///     - StorageT: A custom storage functor class.  An object of this type
  78 ///             will be called as a function with empty Record as an
  79 ///             argument.  The storage class is expected to fill the
  80 ///             record object in preparation for building the packet
  81 ///             out of that data.  These calls happen on the fly as the data
  82 ///             is sent to the device over USB, so it should not block forever.
  83 ///
  84 /// Example SaveDatabase() call:
  85 ///
  86 /// <pre>
  87 /// FIXME
  88 /// </pre>
  89 ///
  90 template <class RecordT, class StorageT>
  91 class RecordBuilder : public Builder
  92 {
  93         StorageT *m_storage;
  94         bool m_owned;
  95         RecordT m_rec;
  96
  97 public:
  98         /// Constructor that references an externally managed storage object.
  99         RecordBuilder(StorageT &storage)
 100                 : m_storage(&storage), m_owned(false) {}
 101
 102         /// Constructor that references a locally managed storage object.
 103         /// The pointer passed in will be stored, and freed when this class
 104         /// is destroyed.  It is safe to call this constructor with
 105         /// a 'new'ly created storage object.
 106         RecordBuilder(StorageT *storage)
 107                 : m_storage(storage), m_owned(true) {}
 108
 109         ~RecordBuilder()
 110         {
 111                 if( this->m_owned )
 112                         delete m_storage;
 113         }
 114
 115         virtual bool Retrieve(unsigned int databaseId)
 116         {
 117                 return (*m_storage)(m_rec, databaseId);
 118         }
 119
 120         virtual uint8_t GetRecType() const
 121         {
 122                 return m_rec.GetRecType();
 123         }
 124
 125         virtual uint32_t GetUniqueId() const
 126         {
 127                 return m_rec.GetUniqueId();
 128         }
 129
 130         /// Functor member called by Controller::SaveDatabase() during
 131         /// processing.
 132         virtual void BuildHeader(Data &data, size_t &offset)
 133         {
 134                 m_rec.BuildHeader(data, offset);
 135         }
 136
 137         virtual void BuildFields(Data &data, size_t &offset, const IConverter *ic)
 138         {
 139                 m_rec.BuildFields(data, offset, ic);
 140         }
 141 };
 142
 143
 144 //
 145 // RecordFetch template class
 146 //
 147 /// Generic record fetch class, to help with using records without
 148 /// builder classes.
 149 ///
 150 template <class RecordT>
 151 class RecordFetch
 152 {
 153         const RecordT &m_rec;
 154         mutable bool m_done;
 155
 156 public:
 157         RecordFetch(const RecordT &rec) : m_rec(rec), m_done(false) {}
 158         bool operator()(RecordT &rec, unsigned int dbId) const
 159         {
 160                 if( m_done )
 161                         return false;
 162                 rec = m_rec;
 163                 m_done = true;
 164                 return true;
 165         }
 166 };
 167
 168
 169 } // namespace Barry
 170
 171 #endif
 172