src/builder.h

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