Efl.Io.Copier (class)

Copy from an Efl.Io.Reader source to Efl.Io.Writer destination.

During usage it will keep reference to Efl.Io.Copier.source and Efl.Io.Copier.destination objects, automatically releasing them on destruction.

By default the read-write process is done based on fixed-size chunks (Efl.Io.Copier.read_chunk_size) but if Efl.Io.Copier.line_delimiter is set, the behavior changes to wait for said delimiter or until a maximum buffer limit is reached (Efl.Io.Copier.buffer_limit).

While a Efl.Io.Copier.source is mandatory for the copier to operate properly the Efl.Io.Copier.destination is optional: if it's not provided, all read data is stored in an internal buffer that can be retrieved using Efl.Io.Copier.binbuf_steal, usually called when one of "data", "line" or "done" events are emitted.

Most important events:

- The "data" event is general and notifies some data was written to Efl.Io.Copier.destination (if any, otherwise it will be reported as data when it's read from Efl.Io.Copier.source).

- The "line" event is only emitted when Efl.Io.Copier.line_delimiter is set and not empty. It's similar to "data".

- The "done" event is emitted if Efl.Io.Copier.source is Efl.Io.Reader.eos true and all data was written to Efl.Io.Copier.destination (if any, otherwise it will be reported when all data is read from Efl.Io.Copier.source).

- The "error" event is reported if the Efl.Io.Reader.read, Efl.Io.Writer.write or some other internal error occurs, such as being out of memory. Another common error is ETIMEDOUT if Efl.Io.Copier.timeout_inactivity is set.

A copier is handy for simplifying common I/O use cases, such as:

- Reading a file or download content to memory: provide only the source and wait for "done" event, calling Efl.Io.Copier.binbuf_steal afterwards.

- Downloading content to disk: provide a network socket as source and use Efl.Io.File as destination, then wait for "done" event.

- Linking two I/O streams: provide both source and destination streams, such as Efl.Io.Stdin and Efl.Io.Stdout, or some network socket. As data is received from source it will be copied to destination in an endless (asynchronous) loop. You may monitor for "done" if the source is closed.

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

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

⇒ Efl.Loop_Consumer (class) ⇒ Efl.Object (class)

Full hierarchy

binbuf_steal

Steals the internal binbuf and returns it to caller.

Eina_Binbuf *efl_io_copier_binbuf_steal(Eo *obj);

buffer_limit (get, set)

Copier buffer limit property, in bytes.

size_t efl_io_copier_buffer_limit_get(const Eo *obj);
void efl_io_copier_buffer_limit_set(Eo *obj, size_t size);

close [Overridden from Efl.Io.Closer]

Closes the Input/Output object.

Eina_Error efl_io_closer_close(Eo *obj);

close_on_exec (get, set) [Overridden from Efl.Io.Closer]

If true will automatically close resources on exec() calls.

Eina_Bool efl_io_closer_close_on_exec_get(const Eo *obj);
Eina_Bool efl_io_closer_close_on_exec_set(Eo *obj, Eina_Bool close_on_exec);

close_on_invalidate (get, set) [Overridden from Efl.Io.Closer]

If true will automatically close() on object invalidate.

Eina_Bool efl_io_closer_close_on_invalidate_get(const Eo *obj);
void efl_io_closer_close_on_invalidate_set(Eo *obj, Eina_Bool close_on_invalidate);

closed (get) [Overridden from Efl.Io.Closer]

Eina_Bool efl_io_closer_closed_get(const Eo *obj);

constructor [Overridden from Efl.Object]

Implement this method to provide optional initialization code for your object.

Efl_Object *efl_constructor(Eo *obj);

destination (get, set)

Copier destination object.

Efl_Io_Writer *efl_io_copier_destination_get(const Eo *obj);
void efl_io_copier_destination_set(Eo *obj, Efl_Io_Writer *destination);

destructor [Overridden from Efl.Object]

Implement this method to provide deinitialization code for your object if you need it.

void efl_destructor(Eo *obj);

done (get, set) protected set

Reports if copier is done.

Eina_Bool efl_io_copier_done_get(const Eo *obj);
void efl_io_copier_done_set(Eo *obj, Eina_Bool done);

finalize [Overridden from Efl.Object]

Implement this method to finish the initialization of your object after all (if any) user-provided configuration methods have been executed.

Efl_Object *efl_finalize(Eo *obj);

flush

Forces reading from source and writing to destination.

Eina_Bool efl_io_copier_flush(Eo *obj, Eina_Bool may_block, Eina_Bool ignore_line_delimiter);

invalidate [Overridden from Efl.Object]

Implement this method to perform special actions when your object loses its parent, if you need to.

void efl_invalidate(Eo *obj);

line_delimiter (get, set)

If there is a line delimiter, reads will buffer/queue up to the line delimiter before calling Efl.Io.Writer.write on the Efl.Io.Copier.destination and the event line is emitted with the current line. The line may include the delimiter unless it's end-of-stream on Efl.Io.Copier.source or Efl.Io.Copier.buffer_limit was reached.

const Eina_Slice efl_io_copier_line_delimiter_get(const Eo *obj);
void efl_io_copier_line_delimiter_set(Eo *obj, const Eina_Slice slice);

pending_size (get)

size_t efl_io_copier_pending_size_get(const Eo *obj);

progress (get)

void efl_io_copier_progress_get(const Eo *obj, uint64_t *read, uint64_t *written, uint64_t *total);

read_chunk_size (get, set)

Copier read chunk size property, in bytes.

size_t efl_io_copier_read_chunk_size_get(const Eo *obj);
void efl_io_copier_read_chunk_size_set(Eo *obj, size_t size);

source (get, set)

Copier source object.

Efl_Io_Reader *efl_io_copier_source_get(const Eo *obj);
void efl_io_copier_source_set(Eo *obj, Efl_Io_Reader *source);

timeout_inactivity (get, set)

Terminates the copier with ETIMEDOUT if it becomes inactive for some time.

double efl_io_copier_timeout_inactivity_get(const Eo *obj);
void efl_io_copier_timeout_inactivity_set(Eo *obj, double seconds);

data

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.

EFL_IO_COPIER_EVENT_DATA(const Eina_Slice *)

done

All available data was copied from source to destination

EFL_IO_COPIER_EVENT_DONE(void)

error

An error happened and the copy stopped

EFL_IO_COPIER_EVENT_ERROR(Eina_Error)

line

If Efl.Io.Copier.line_delimiter is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified.

EFL_IO_COPIER_EVENT_LINE(const Eina_Slice *)

progress

Total size changed or Data was read/written

EFL_IO_COPIER_EVENT_PROGRESS(void)