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