xorriso  1.5.4.pl02
About: GNU xorriso creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. It is suitable for incremental data backup and for production of bootable ISO 9660 images. GNU xorriso is a statical compilation of the libraries libburn, libisofs, libisoburn, and libjte.
  Fossies Dox: xorriso-1.5.4.pl02.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

burn_source Struct Reference

#include <libburn.h>

Collaboration diagram for burn_source:
[legend]

Data Fields

int refcount
 
int(* read )(struct burn_source *, unsigned char *buffer, int size)
 
int(* read_sub )(struct burn_source *, unsigned char *buffer, int size)
 
off_t(* get_size )(struct burn_source *)
 
int(* set_size )(struct burn_source *source, off_t size)
 
void(* free_data )(struct burn_source *)
 
struct burn_sourcenext
 
void * data
 
int version
 
int(* read_xt )(struct burn_source *, unsigned char *buffer, int size)
 
int(* cancel )(struct burn_source *source)
 

Detailed Description

Data source interface for tracks. This allows you to use arbitrary program code as provider of track input data.

Objects compliant to this interface are either provided by the application or by API calls of libburn: burn_fd_source_new() , burn_file_source_new(), and burn_fifo_source_new().

The API calls may use any file object as data source. Consider to feed an eventual custom data stream asynchronously into a pipe(2) and to let libburn handle the rest. In this case the following rule applies: Call burn_source_free() exactly once for every source obtained from libburn API. You MUST NOT otherwise use or manipulate its components.

In general, burn_source objects can be freed as soon as they are attached to track objects. The track objects will keep them alive and dispose them when they are no longer needed. With a fifo burn_source it makes sense to keep the own reference for inquiring its state while burning is in progress.


The following description of burn_source applies only to application implemented burn_source objects. You need not to know it for API provided ones.

If you really implement an own passive data producer by this interface, then beware: it can do anything and it can spoil everything.

In this case the functions (*read), (*get_size), (*set_size), (*free_data) MUST be implemented by the application and attached to the object at creation time. Function (*read_sub) is allowed to be NULL or it MUST be implemented and attached.

burn_source.refcount MUST be handled properly: If not exactly as many references are freed as have been obtained, then either memory leaks or corrupted memory are the consequence. All objects which are referred to by *data must be kept existent until (*free_data) is called via burn_source_free() by the last referer.

Definition at line 463 of file libburn.h.

Field Documentation

◆ cancel

int(* burn_source::cancel) (struct burn_source *source)

Informs the burn_source that the consumer of data prematurely ended reading. This call may or may not be issued by libburn before (*free_data)() is called.

Definition at line 581 of file libburn.h.

Referenced by burn_fifo_source_new(), burn_offst_source_new(), burn_source_cancel(), iso_image_create_burn_source(), and isoburn_cancel_prepared_write().

◆ data

void* burn_source::data

Source specific data. Here the various source classes express their specific properties and the instance objects store their individual management data. E.g. data could point to a struct like this: struct app_burn_source { struct my_app *app_handle; ... other individual source parameters ... off_t fixed_size; };

Function (*free_data) has to be prepared to clean up and free the struct.

Definition at line 557 of file libburn.h.

Referenced by bs_cancel(), bs_free_data(), bs_get_size(), bs_read(), bs_set_size(), burn_fd_source_new(), burn_fifo_cancel(), burn_fifo_fill_data(), burn_fifo_get_statistics(), burn_fifo_inquire_status(), burn_fifo_next_interval(), burn_fifo_source_new(), burn_fifo_source_shoveller(), burn_fifo_start(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), fifo_free(), fifo_get_size(), fifo_read(), fifo_set_size(), file_free(), file_read(), file_read_sub(), file_set_size(), file_size(), get_bytes(), iso_image_create_burn_source(), iso_ring_buffer_get_status(), iso_write_opts_set_system_area(), offst_auth(), and offst_free().

◆ free_data

void(* burn_source::free_data) (struct burn_source *)

Clean up the source specific data. This function will be called once by burn_source_free() when the last referer disposes the source.

Definition at line 533 of file libburn.h.

Referenced by burn_fd_source_new(), burn_fifo_inquire_status(), burn_fifo_source_new(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), burn_source_free(), iso_image_create_burn_source(), and offst_auth().

◆ get_size

off_t(* burn_source::get_size) (struct burn_source *)

Get the size of the source's data. Return 0 means unpredictable size. If application provided (*get_size) might return 0, then the application MUST provide a fully functional (*set_size).

Definition at line 509 of file libburn.h.

Referenced by burn_fd_source_new(), burn_fifo_source_new(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), burn_track_apply_fillup(), burn_track_get_sectors_2(), burn_track_get_shortage(), burn_track_set_sectors(), fifo_get_size(), and iso_image_create_burn_source().

◆ next

struct burn_source* burn_source::next

Next source, for when a source runs dry and padding is disabled WARNING: This is an obscure feature. Set to NULL at creation and from then on leave untouched and uninterpreted.

Definition at line 540 of file libburn.h.

Referenced by burn_create_toc_entries(), and get_bytes().

◆ read

int(* burn_source::read) (struct burn_source *, unsigned char *buffer, int size)

Read data from the source. Semantics like with read(2), but MUST either deliver the full buffer as defined by size or MUST deliver EOF (return 0) or failure (return -1) at this call or at the next following call. I.e. the only incomplete buffer may be the last one from that source. libburn will read a single sector by each call to (read). The size of a sector depends on BURN_MODE_. The known range is 2048 to 2352.

If this call is reading from a pipe then it will learn
about the end of data only when that pipe gets closed on the
feeder side. So if the track size is not fixed or if the pipe
delivers less than the predicted amount or if the size is not
block aligned, then burning will halt until the input process
closes the pipe.

IMPORTANT: If this function pointer is NULL, then the struct burn_source is of version >= 1 and the job of .(*read)() is done by .(*read_xt)(). See below, member .version.

Definition at line 493 of file libburn.h.

Referenced by burn_fd_source_new(), burn_fifo_source_new(), burn_fifo_source_shoveller(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), burn_source_cancel(), burn_source_read(), burn_stdio_read_source(), get_bytes(), iso_image_create_burn_source(), and isoburn_cancel_prepared_write().

◆ read_sub

int(* burn_source::read_sub) (struct burn_source *, unsigned char *buffer, int size)

Read subchannel data from the source (NULL if lib generated) WARNING: This is an obscure feature with CD raw write modes. Unless you checked the libburn code for correctness in that aspect you should not rely on raw writing with own subchannels. ADVICE: Set this pointer to NULL.

Definition at line 502 of file libburn.h.

Referenced by burn_fd_source_new(), burn_fifo_source_new(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), file_free(), and sector_data().

◆ read_xt

int(* burn_source::read_xt) (struct burn_source *, unsigned char *buffer, int size)

This substitutes for (*read)() in versions above 0.

Definition at line 575 of file libburn.h.

Referenced by burn_fifo_source_new(), burn_fifo_source_shoveller(), burn_offst_source_new(), burn_source_read(), burn_stdio_read_source(), get_bytes(), and iso_image_create_burn_source().

◆ refcount

int burn_source::refcount

Reference count for the data source. MUST be 1 when a new source is created and thus the first reference is handed out. Increment it to take more references for yourself. Use burn_source_free() to destroy your references to it.

Definition at line 469 of file libburn.h.

Referenced by burn_fifo_source_new(), burn_null_source_new(), burn_offst_source_new(), burn_source_free(), burn_source_new(), and iso_image_create_burn_source().

◆ set_size

int(* burn_source::set_size) (struct burn_source *source, off_t size)

Program the reply of (*get_size) to a fixed value. It is advised to implement this by a attribute off_t fixed_size; in *data . The read() function does not have to take into respect this fake setting. It is rather a note of libburn to itself. Eventually necessary truncation or padding is done in libburn. Truncation is usually considered a misburn. Padding is considered ok.

libburn is supposed to work even if (*get_size) ignores the setting by (*set_size). But your application will not be able to enforce fixed track sizes by burn_track_set_size() and possibly even padding might be left out.

Definition at line 526 of file libburn.h.

Referenced by burn_fd_source_new(), burn_fifo_source_new(), burn_file_source_new(), burn_null_source_new(), burn_offst_source_new(), burn_track_set_sectors(), burn_track_set_size(), fifo_set_size(), and iso_image_create_burn_source().

◆ version

int burn_source::version

Valid only if above member .(*read)() is NULL. This indicates a version of struct burn_source younger than 0. From then on, member .version tells which further members exist in the memory layout of struct burn_source. libburn will only touch those announced extensions.

Versions: 0 has .(*read)() != NULL, not even .version is present. 1 has .version, .(*read_xt)(), .(*cancel)()

Definition at line 572 of file libburn.h.

Referenced by burn_fifo_source_new(), burn_offst_source_new(), burn_source_cancel(), iso_image_create_burn_source(), and isoburn_cancel_prepared_write().


The documentation for this struct was generated from the following file: