efl/src/lib/ecore/efl_io_copier.eo

import eina_types;

class Efl.Io.Copier (Efl.Loop_User, Efl.Io.Closer) {
    [[Copy from an @Efl.Io.Reader source to @Efl.Io.Writer destination.

      During usage it will keep reference to @.source and
      @.destination objects, automatically relasing them on
      destructor.

      By default the read-write process is done based on fixed-size
      chunks (@.read_chunk_size), however if @.line_delimiter is set,
      the behavior changes to wait for such delimiter or a maximum
      buffer limit is reached (@.buffer_limit).

      If @Efl.Io.Closer.close is called, then it will be called on
      @.source and @.destination if they implement those interfaces.

      @Efl.Io.Closer.close_on_exec and
      @Efl.Io.Closer.close_on_destructor are respected and applied to
      both source and destination. Both default to $true.

      @since 1.19
    ]]

    methods {
        @property source {
           [[Copier source property]]
           get {
           }
           set {
                [[Constructor-only property to set where to read data from]]
           }
           values {
                source: Efl.Io.Reader; [[Reader source]]
           }
        }

        @property destination {
           [[Copier destination property]]
           get {
           }
           set {
                [[Constructor-only property to set where to write data to]]
           }
           values {
                destination: Efl.Io.Writer; [[Writer destination]]
           }
        }

        @property line_delimiter {
            [[If there is a line delimiter, the reads will buffer/queue up to the line delimiter before calling @Efl.Io.Writer.write on the @.destination and the event line is emitted with current line. The line may include the delimiter, unless it's end-of-stream on @.source or @.buffer_limit was reached.]]
            get { }
            set {
               [[Change line delimiter to use. If NULL or empty, no delimiter is to be used]]
            }
            values {
                slice: ptr(const(Eina.Slice)); [[The contents may contain \0 and will be copied]]
            }
        }

        @property buffer_limit {
           [[Copier buffer limit property]]
           get {
           }
           set {
                [[Constructor-only property to set buffer limit. 0 is unlimited]]
           }
           values {
                size: size; [[Defines a maximum buffer limit, or 0 to allow unlimited amount of bytes]]
           }
        }

        @property read_chunk_size {
           [[Copier read chunk size property]]
           get {
           }
           set {
                [[Set chunk size for each basic @Efl.Io.Reader.read operation.]]
           }
           values {
                size: size; [[This is the chunk size to use for read operations]]
           }
        }

        @property progress {
            [[Progress for read or write]]
            get {
            }
            values {
                read: uint64 @optional; [[Amount of bytes read from source]]
                written: uint64 @optional; [[Amount of bytes written to destination]]
                total: uint64 @optional; [[If @.source is an Efl.Io.Sizer, its total size. Otherwise 0 to report unknown size]]
           }
        }

        @property inactivity_timeout {
            [[Terminate the copier with ETIMEDOUT if it becomes inactive for some time.

              If the copier cannot do any read or write in the given
              amount of seconds, then the copier will emit "error"
              event with ETIMEDOUT value.

              This is specified in seconds and is only active for
              greater-than zero. Defaults to inactive.
            ]]
            values {
                seconds: double; [[Number inactive seconds to timeout this copier. If zero or less, it will be disabled.]]
            }
        }

        binbuf_steal {
           [[Steals the internal binbuf and return it to caller.

             The buffer is then owned by caller, which should call
             eina_binbuf_free() when it's done.
           ]]
           return: free(own(ptr(Eina.Binbuf)), eina_binbuf_free) @warn_unused; [[Binbuf]]
        }

        flush {
            [[Forces reading from source and writing to destination.

              This executes a single read->write cycle, if more data
              could be read from source (ie: not EOS) or not all data
              was written to destination, then $false is
              returned. Then to forcefully drain source and write all
              contents to destination, use in a loop until it returns
              $true.

              The return value matches "done" event, that is, when
              $true is returned, the "done" event is emitted.

              This function may also emit "progress" and "error"
              events.

              \@note this function may block the main loop execution
              until operations complete! This is bad for usability, as
              user interface or other operations may freeze. A better
              approach is to operate asynchronously and wait for
              "done" event.
            ]]
            return: bool(true); [[$true on success, $false otherwise]]
        }
    }

    events {
        done; [[All available data was copied from source to destination]]
        error: Eina.Error; [[An error happened and the copy stopped]]
        progress; [[Total size changed or Data was read/written]]
        data: ptr(const(Eina.Slice)); [[When data is read to internal buffer, it's emitted in this event. The memory is only valid during event callback dispatched and should not be modified.]]
        line: ptr(const(Eina.Slice)); [[If @.line_delimiter is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified.]]
    }

    implements {
       Efl.Object.constructor;
       Efl.Object.destructor;
       Efl.Object.finalize;
       Efl.Io.Closer.close;
       Efl.Io.Closer.closed.get;
       Efl.Io.Closer.close_on_exec;
       Efl.Io.Closer.close_on_destructor;
    }
}