home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / yacl-012.zip / io / bytstore.h < prev    next >
C/C++ Source or Header  |  1995-04-08  |  6KB  |  171 lines
  1.  
  2.  
  3. #ifndef _bytstore_h_
  4. #define _bytstore_h_
  5.  
  6.  
  7. /*
  8.  *
  9.  *          Copyright (C) 1994, M. A. Sridhar
  10.  *  
  11.  *
  12.  *     This software is Copyright M. A. Sridhar, 1994. You are free
  13.  *     to copy, modify or distribute this software  as you see fit,
  14.  *     and to use  it  for  any  purpose, provided   this copyright
  15.  *     notice and the following   disclaimer are included  with all
  16.  *     copies.
  17.  *
  18.  *                        DISCLAIMER
  19.  *
  20.  *     The author makes no warranties, either expressed or implied,
  21.  *     with respect  to  this  software, its  quality, performance,
  22.  *     merchantability, or fitness for any particular purpose. This
  23.  *     software is distributed  AS IS.  The  user of this  software
  24.  *     assumes all risks  as to its quality  and performance. In no
  25.  *     event shall the author be liable for any direct, indirect or
  26.  *     consequential damages, even if the  author has been  advised
  27.  *     as to the possibility of such damages.
  28.  *
  29.  */
  30.  
  31.  
  32.  
  33. // This  is  ByteStringStore, a   class that  encapsulates a  facility  for
  34. // storing byte strings  of arbitrary sizes into a  file, via a handle, and
  35. // retrieving them for subsequent use. A user  of this class  can add a new
  36. // byte string to the store, thus obtaining an associated handle (using the
  37. // Add method), and later  retrieve the byte   string by specifying  that
  38. // handle (using the Retrieve method). Byte strings currently stored in the
  39. // store may be modified via  the Modify method; this modification includes
  40. // changing either the data or the length (or both) of the byte string.
  41. // 
  42. // Byte strings may be removed from  the store via  the Remove method; this
  43. // renders the associated handle invalid.
  44. // 
  45. // This class  also provides two methods,  ReadHeader  and WriteHeader, for
  46. // manipulating a "user-defined" header. A  client of this object may store
  47. // client-specific header information in this header.  Note that the header
  48. // need not be of fixed length.
  49.  
  50.  
  51.  
  52.  
  53. #if defined(__GNUC__)
  54. #pragma interface
  55. #endif
  56.  
  57.  
  58. #include "base/bytstrng.h"
  59. #include "io/slotfile.h"
  60.  
  61. class CL_EXPORT CL_ByteStringStore: public CL_Object {
  62.  
  63.  
  64. public:
  65.  
  66.     // ----------------------- Constructors/destructors -----------------
  67.  
  68.     CL_ByteStringStore (const char* path, bool create = FALSE, bool
  69.                        report_errors = TRUE);
  70.     // Construct a CL_ByteStringStore on the given file. If {\tt create}
  71.     // is TRUE, create a new file with the given name, overwriting any
  72.     // existing one. If {\tt report_errors} is TRUE, then issue error
  73.     // messages through {\tt CL_Error} when i/o errors occur.
  74.  
  75.     ~CL_ByteStringStore();
  76.     // Destructor: close the ByteStringStore.
  77.  
  78.     // ------------------------ Storage and retrieval -------------------
  79.  
  80.     virtual CL_SlottedFileHandle Allocate ();
  81.     // Allocate a handle at which a new ByteString can be stored, and
  82.     // return it.
  83.     
  84.     virtual CL_SlottedFileHandle Add (const CL_ByteArray& data);
  85.     // Add the given array of bytes into the store, and return the
  86.     // associated handle. Return 0 on failure (e.g., due to I/O error).
  87.  
  88.     virtual bool Remove (CL_SlottedFileHandle h);
  89.     // Remove the byte string associated with the given handle. Return
  90.     // TRUE on success, FALSE if either the handle was invalid or an I/O
  91.     // error occurred.
  92.  
  93.     virtual bool Retrieve  (CL_SlottedFileHandle h,
  94.                             CL_ByteString& value) const;
  95.     // Retrieve the byte string associated with the given handle (first
  96.     // parameter), and return it in the second. Return TRUE as the
  97.     // function value if successful, FALSE on I/O error or invalid handle.
  98.  
  99.     virtual bool Modify (CL_SlottedFileHandle h, const CL_ByteArray& b);
  100.     // Modify the byte string associated with the given handle (first
  101.     // parameter) to be equal to the second parameter. Note that the
  102.     // length of the second parameter need not bear any relationship to
  103.     // the length of the string currently associated with the given handle.
  104.     //     Return TRUE as the function value if successful, FALSE on I/O
  105.     // error or invalid handle.
  106.  
  107.  
  108.     // ------------------- Manipulating user headers ------------------
  109.  
  110.     virtual bool ReadHeader (CL_ByteString& header) const;
  111.     // Read and return the user-defined header in the file. Returns
  112.     // TRUE on success, FALSE on i/o error.
  113.  
  114.     virtual bool WriteHeader (const CL_ByteString& header);
  115.     // Write the parameter into the user-defined header. Returns
  116.     // TRUE on success, FALSE on i/o error.
  117.  
  118.  
  119.     // ---------------------- Basic methods ----------------------------
  120.  
  121.     const char* ClassName () const { return "CL_ByteStringStore";};
  122.  
  123.     // ---------------------- End public protocol -------------------
  124.  
  125. protected:
  126.     CL_SlottedFileHandle _Add    (uchar* data, long data_size);
  127.     
  128.     bool                 _Remove (CL_SlottedFileHandle);
  129.     
  130.     bool                 _Retrieve  (CL_SlottedFileHandle h,
  131.                                      CL_ByteString& value,
  132.                                      CL_SlottedFileHandle& itr_next) const;
  133.     
  134.  
  135.     class CL_SlottedFile* _file;
  136.     friend class CL_ByteStoreIterator;
  137.     
  138. };
  139.  
  140.  
  141.  
  142. class CL_ByteStoreIterator {
  143.  
  144. public:
  145.     CL_ByteStoreIterator (const CL_ByteStringStore&);
  146.     // Constructor.
  147.  
  148.     CL_ByteStoreIterator (const CL_ByteStoreIterator&);
  149.     // Copy constructor.
  150.  
  151.     // -------------------- Iteration methods -------------------------
  152.  
  153.     virtual void Reset ();
  154.     // The Reset and Next methods retrieve the ByteStrings in the file, in
  155.     // no particular order. The Reset method begins the iteration.
  156.  
  157.     virtual CL_SlottedFileHandle Next (CL_ByteString& value);
  158.     // Return the next ByteString in sequence, in the parameter, and
  159.     // return its handle as the function value. Return 0 when there are no
  160.     // more ByteStrings.
  161.  
  162.  
  163. protected:
  164.     CL_SlottedFileHandle      _next;
  165.     const CL_ByteStringStore& _store;
  166.     
  167. };
  168.  
  169.  
  170. #endif
  171.