Home | History | Annotate | Download | only in base
      1 #ifndef IMAGE_IO_BASE_DATA_DESTINATION_H_  // NOLINT
      2 #define IMAGE_IO_BASE_DATA_DESTINATION_H_  // NOLINT
      3 
      4 #include "image_io/base/data_range.h"
      5 #include "image_io/base/data_segment.h"
      6 #include "image_io/base/types.h"
      7 
      8 namespace photos_editing_formats {
      9 namespace image_io {
     10 
     11 /// DataDestination is the abstract base class for implementations that can
     12 /// efficiently move data from one location and/or form to another. In such
     13 /// a transfer, the StartTransfer() and FinishTransfer() functions are always
     14 /// called, and in between the Transfer() function may be called zero or more
     15 /// times. See the DataSource class to see how to initiate a transfer operation.
     16 class DataDestination {
     17  public:
     18   /// These values indicate what should be done after a DataSource calls a
     19   /// DataDestination's Transfer() function.
     20   enum TransferStatus {
     21     /// An error occurred in the transfer process. DataSource's TransferData()
     22     /// function should stop calling DataDestination's Transfer() function, and
     23     /// return to its caller.
     24     kTransferError,
     25 
     26     /// The transfer was successful. DataSource's TransferData() function can
     27     /// keep calling DataDestination's Transfer() of needed, or if not,
     28     /// return to its caller.
     29     kTransferOk,
     30 
     31     /// The transfer was successful and the DataDestination has decided that
     32     /// it has enough data. DataSource's TransferData() function should stop
     33     /// calling DataDestination's Transfer() function and return to its caller.
     34     kTransferDone
     35   };
     36 
     37   virtual ~DataDestination() = default;
     38 
     39   /// This function is called prior to the first call to the Transfer() function
     40   /// to allow implementation subclasses a chance to initialize their data
     41   /// members for the transfer process. If a data destination sends its bytes
     42   /// to another data destination, this function must call its StartTransfer()
     43   /// function.
     44   virtual void StartTransfer() = 0;
     45 
     46   /// This function is called to transfer a portion or all of the data in the
     47   /// data segment from the caller to wherever the receiver needs it to go.
     48   /// @param transfer_range The portion of the data in the data_segment that is
     49   ///     to be transferred.
     50   /// @param data_segment The data, some or all of which is to be transferred.
     51   /// @return A transfer status value indicating what should be done next.
     52   virtual TransferStatus Transfer(const DataRange& transfer_range,
     53                                   const DataSegment& data_segment) = 0;
     54 
     55   /// This function is called after the final call to the Transfer() function to
     56   /// allow implementation subclasses a chance to finalize their transfer
     57   /// operations.  If a data destination sends its bytes to another data
     58   /// destination, this function must call its FinishTransfer() function.
     59   virtual void FinishTransfer() = 0;
     60 
     61   /// @return The number of bytes written to the data destination. There is some
     62   /// flexibility in the actual value returned. Most "end-point" destination
     63   /// subclasses return the actual number of bytes received/written. Other
     64   /// "mid-point" destinations are allowed to return the value from the next
     65   /// destination in the chain, or the actual number of bytes they are asked
     66   /// to transfer via the transfer_range parameter of the Transfer()
     67   /// function.
     68   virtual size_t GetBytesTransferred() const = 0;
     69 };
     70 
     71 }  // namespace image_io
     72 }  // namespace photos_editing_formats
     73 
     74 #endif // IMAGE_IO_BASE_DATA_DESTINATION_H_  // NOLINT
     75