src/builder.h

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