nucleus/library/filesystem/heavy_file_ops.h

   1 #ifndef HEAVY_FILE_OPERATIONS_CLASS
   2 #define HEAVY_FILE_OPERATIONS_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : heavy file operations                                             *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2005-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "filename_list.h"
  19
  20 #include <basis/astring.h>
  21 #include <basis/contracts.h>
  22
  23 namespace filesystem {
  24
  25 //! describes one portion of an ongoing file transfer.
  26 /*! this is just a header describing an attached byte package.  it is expected
  27 that the bytes follow this in the communication stream. */
  28
  29 class file_transfer_header : public basis::packable
  30 {
  31 public:
  32   basis::astring _filename;  //!< the name of the file being transferred.
  33 //hmmm: consider adding full length here so we know it.
  34   double _byte_start;  //!< the starting location in the file being sent.
  35   int _length;  //!< the length of the transferred piece.
  36   file_time _time;  //!< the timestamp on the file.
  37
  38   DEFINE_CLASS_NAME("file_transfer_header");
  39
  40   file_transfer_header(const file_time &time_stamp);
  41     //!< refactored to force addition of the time_stamp.
  42
  43   virtual void pack(basis::byte_array &packed_form) const;
  44   virtual bool unpack(basis::byte_array &packed_form);
  45
  46   virtual int packed_size() const;
  47
  48   basis::astring text_form() const;
  49
  50 //hmmm: this could live in lots of other places.  file_info for one.
  51   basis::astring readable_text_form() const;
  52     //!< a nicer formatting of the information.
  53 };
  54
  55 //////////////
  56
  57 //! Provides serious file operations, such as copy and partial writing.
  58
  59 class heavy_file_operations : public virtual basis::root_object
  60 {
  61 public:
  62   virtual ~heavy_file_operations();
  63
  64   enum outcomes {
  65     OKAY = basis::common::OKAY,
  66     BAD_INPUT = basis::common::BAD_INPUT,
  67     FINISHED = basis::common::IS_EMPTY,  // nothing left to pack.
  68     DEFINE_OUTCOME(SOURCE_MISSING, -43, "The source file is not accessible"),
  69     DEFINE_OUTCOME(TARGET_DIR_ERROR, -44, "The target's directory could not "
  70         "be created"),
  71     DEFINE_OUTCOME(TARGET_ACCESS_ERROR, -45, "The target file could not be "
  72         "created")
  73   };
  74   static const char *outcome_name(const basis::outcome &to_name);
  75
  76   DEFINE_CLASS_NAME("heavy_file_operations");
  77
  78   static const size_t COPY_CHUNK_FACTOR;
  79     //!< the default copy chunk size for the file copy method.
  80   static size_t copy_chunk_factor();
  81     //!< method can be exported for use by shared libs.
  82
  83   static basis::outcome copy_file(const basis::astring &source, const basis::astring &destination,
  84           int copy_chunk_factor = heavy_file_operations::copy_chunk_factor());
  85     //!< copies a file from the "source" location to the "destination".
  86     /*!< the outcomes could be from this class or from common::outcomes.
  87     the "copy_chunk_factor" is the read buffer size to use while copying. */
  88
  89   static basis::outcome write_file_chunk(const basis::astring &target, double byte_start,
  90           const basis::byte_array &chunk, bool truncate = true,
  91           int copy_chunk_factor = heavy_file_operations::copy_chunk_factor());
  92     //!< stores a chunk of bytes into the "target" file.
  93     /*!< writes the content stored in "chunk" into the file "target" at the
  94     position "byte_start".  the entire "chunk" will be used, which means the
  95     file will either be that much larger or have the space between byte_start
  96     and (byte_start + chunk.length() - 1) replaced.  if the file is not yet as
  97     large as "byte_start", then it will be expanded appropriately.  if
  98     "truncate" is true, then any contents past the new chunk are dropped from
  99     the file. */
 100
 101   static basis::outcome buffer_files(const basis::astring &source_root,
 102           const filename_list &to_transfer, file_transfer_header &last_action,
 103           basis::byte_array &storage, int maximum_bytes);
 104     //!< reads files in "to_transfer" and packs them into a "storage" buffer.
 105     /*!< the maximum size allowed in storage is "maximum_bytes".  the record
 106     of the last file piece stored in "last_action" allows the next chunk
 107     to be sent in subsequent calls.  note that the buffer "storage" is cleared
 108     out before bytes are stored into it; this is not an additive operation. */
 109
 110 private:
 111   static basis::outcome advance(const filename_list &to_transfer,
 112           file_transfer_header &last_action);
 113     //!< advances to the next file in the transfer list "to_transfer".
 114 };
 115
 116 //////////////
 117
 118 } //namespace.
 119
 120 #endif
 121