<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libburn: burn_source Struct Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="functions.html"><span>Data Fields</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>burn_source Struct Reference</h1><!-- doxytag: class="burn_source" -->
<p>Data source interface for tracks.
<a href="#_details">More...</a></p>
<p><code>#include <<a class="el" href="libburn_8h_source.html">libburn.h</a>></code></p>
<div class="dynheader">
Collaboration diagram for burn_source:</div>
<div class="dynsection">
<div class="center"><img src="structburn__source__coll__graph.png" border="0" usemap="#burn__source_coll__map" alt="Collaboration graph"/></div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Fields</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#ada75710f35fe822c592b37d01505609d">refcount</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Reference count for the data source. <a href="#ada75710f35fe822c592b37d01505609d"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a200c110bc2478463843b7779b8a25493">read</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Read data from the source. <a href="#a200c110bc2478463843b7779b8a25493"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#ad8332b0edc6e32c2416ea17abbc37a34">read_sub</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Read subchannel data from the source (NULL if lib generated) WARNING: This is an obscure feature with CD raw write modes. <a href="#ad8332b0edc6e32c2416ea17abbc37a34"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">off_t(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a905045f75e49e37fe913a44b01cface8">get_size</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the size of the source's data. <a href="#a905045f75e49e37fe913a44b01cface8"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a14da00d9e877e6d83ccdee7e8df00158">set_size</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *source, off_t size)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Program the reply of (*get_size) to a fixed value. <a href="#a14da00d9e877e6d83ccdee7e8df00158"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a0267cb87e07dba714ec2f1201c8dc592">free_data</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Clean up the source specific data. <a href="#a0267cb87e07dba714ec2f1201c8dc592"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structburn__source.html">burn_source</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#ac44857dc438cf3790abe5a4b6b337a39">next</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Next source, for when a source runs dry and padding is disabled WARNING: This is an obscure feature. <a href="#ac44857dc438cf3790abe5a4b6b337a39"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#ae42ab808c7ce51af973a76c841cc6dae">data</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Source specific data. <a href="#ae42ab808c7ce51af973a76c841cc6dae"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#af7f96269792e56ee68c112f1e9e4027f">version</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Valid only if above member . <a href="#af7f96269792e56ee68c112f1e9e4027f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a7756a887e9dd87f4cfa928b781ae2f16">read_xt</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">This substitutes for (*read)() in versions above 0. <a href="#a7756a887e9dd87f4cfa928b781ae2f16"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="structburn__source.html#a9652a8d8f500f701ab579a3ed4e313e3">cancel</a> )(struct <a class="el" href="structburn__source.html">burn_source</a> *source)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Informs the <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> that the consumer of data prematurely ended reading. <a href="#a9652a8d8f500f701ab579a3ed4e313e3"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Data source interface for tracks. </p>
<p>This allows to use arbitrary program code as provider of track input data.</p>
<p>Objects compliant to this interface are either provided by the application or by API calls of libburn: <a class="el" href="libburn_8h.html#a2e1504f4c949b13cea988e31af9c150a" title="Creates a data source for an image file (a track) from an open readable filedescriptor...">burn_fd_source_new()</a> , <a class="el" href="libburn_8h.html#aca8c7115fa2b60c2822deb48be8fd0c1" title="Creates a data source for an image file (and maybe subcode file).">burn_file_source_new()</a>, and <a class="el" href="libburn_8h.html#a2d7a2faac8565ddd40d9e6ddae0bd922" title="Creates a fifo which acts as proxy for an already existing data source.">burn_fifo_source_new()</a>.</p>
<p>The API calls allow to 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 <a class="el" href="libburn_8h.html#a1a03f8b3088b8ce6305e7a48c3e034eb" title="Free a burn_source (decrease its refcount and maybe free it).">burn_source_free()</a> exactly once for every source obtained from libburn API. You MUST NOT otherwise use or manipulate its components.</p>
<p>In general, <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> 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 <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> it makes sense to keep the own reference for inquiring its state while burning is in progress.</p>
<p>---</p>
<p>The following description of <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> applies only to application implemented <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> objects. You need not to know it for API provided ones.</p>
<p>If you really implement an own passive data producer by this interface, then beware: it can do anything and it can spoil everything.</p>
<p>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.</p>
<p><a class="el" href="structburn__source.html#ada75710f35fe822c592b37d01505609d" title="Reference count for the data source.">burn_source.refcount</a> 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 <a class="el" href="libburn_8h.html#a1a03f8b3088b8ce6305e7a48c3e034eb" title="Free a burn_source (decrease its refcount and maybe free it).">burn_source_free()</a> by the last referer. </p>
<p>Definition at line <a class="el" href="libburn_8h_source.html#l00396">396</a> of file <a class="el" href="libburn_8h_source.html">libburn.h</a>.</p>
<hr/><h2>Field Documentation</h2>
<a class="anchor" id="a9652a8d8f500f701ab579a3ed4e313e3"></a><!-- doxytag: member="burn_source::cancel" ref="a9652a8d8f500f701ab579a3ed4e313e3" args=")(struct burn_source *source)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int(* <a class="el" href="structburn__source.html#a9652a8d8f500f701ab579a3ed4e313e3">burn_source::cancel</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *source)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Informs the <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> that the consumer of data prematurely ended reading. </p>
<p>This call may or may not be issued by libburn before (*free_data)() is called. </p>
</div>
</div>
<a class="anchor" id="ae42ab808c7ce51af973a76c841cc6dae"></a><!-- doxytag: member="burn_source::data" ref="ae42ab808c7ce51af973a76c841cc6dae" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void* <a class="el" href="structburn__source.html#ae42ab808c7ce51af973a76c841cc6dae">burn_source::data</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Source specific data. </p>
<p>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; };</p>
<p>Function (*free_data) has to be prepared to clean up and free the struct. </p>
<p>Definition at line <a class="el" href="libburn_8h_source.html#l00490">490</a> of file <a class="el" href="libburn_8h_source.html">libburn.h</a>.</p>
</div>
</div>
<a class="anchor" id="a0267cb87e07dba714ec2f1201c8dc592"></a><!-- doxytag: member="burn_source::free_data" ref="a0267cb87e07dba714ec2f1201c8dc592" args=")(struct burn_source *)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void(* <a class="el" href="structburn__source.html#a0267cb87e07dba714ec2f1201c8dc592">burn_source::free_data</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Clean up the source specific data. </p>
<p>This function will be called once by <a class="el" href="libburn_8h.html#a1a03f8b3088b8ce6305e7a48c3e034eb" title="Free a burn_source (decrease its refcount and maybe free it).">burn_source_free()</a> when the last referer disposes the source. </p>
</div>
</div>
<a class="anchor" id="a905045f75e49e37fe913a44b01cface8"></a><!-- doxytag: member="burn_source::get_size" ref="a905045f75e49e37fe913a44b01cface8" args=")(struct burn_source *)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">off_t(* <a class="el" href="structburn__source.html#a905045f75e49e37fe913a44b01cface8">burn_source::get_size</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the size of the source's data. </p>
<p>Return 0 means unpredictable size. If application provided (*get_size) allows return 0, then the application MUST provide a fully functional (*set_size). </p>
</div>
</div>
<a class="anchor" id="ac44857dc438cf3790abe5a4b6b337a39"></a><!-- doxytag: member="burn_source::next" ref="ac44857dc438cf3790abe5a4b6b337a39" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">struct <a class="el" href="structburn__source.html">burn_source</a>* <a class="el" href="structburn__source.html#ac44857dc438cf3790abe5a4b6b337a39">burn_source::next</a><code> [read]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Next source, for when a source runs dry and padding is disabled WARNING: This is an obscure feature. </p>
<p>Set to NULL at creation and from then on leave untouched and uninterpreted. </p>
<p>Definition at line <a class="el" href="libburn_8h_source.html#l00473">473</a> of file <a class="el" href="libburn_8h_source.html">libburn.h</a>.</p>
</div>
</div>
<a class="anchor" id="a200c110bc2478463843b7779b8a25493"></a><!-- doxytag: member="burn_source::read" ref="a200c110bc2478463843b7779b8a25493" args=")(struct burn_source *, unsigned char *buffer, int size)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int(* <a class="el" href="structburn__source.html#a200c110bc2478463843b7779b8a25493">burn_source::read</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Read data from the source. </p>
<p>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.</p>
<p>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.</p>
<p>IMPORTANT: If this function pointer is NULL, then the struct <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> is of version >= 1 and the job of .(*read)() is done by .(*read_xt)(). See below, member .version. </p>
</div>
</div>
<a class="anchor" id="ad8332b0edc6e32c2416ea17abbc37a34"></a><!-- doxytag: member="burn_source::read_sub" ref="ad8332b0edc6e32c2416ea17abbc37a34" args=")(struct burn_source *, unsigned char *buffer, int size)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int(* <a class="el" href="structburn__source.html#ad8332b0edc6e32c2416ea17abbc37a34">burn_source::read_sub</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Read subchannel data from the source (NULL if lib generated) WARNING: This is an obscure feature with CD raw write modes. </p>
<p>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. </p>
</div>
</div>
<a class="anchor" id="a7756a887e9dd87f4cfa928b781ae2f16"></a><!-- doxytag: member="burn_source::read_xt" ref="a7756a887e9dd87f4cfa928b781ae2f16" args=")(struct burn_source *, unsigned char *buffer, int size)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int(* <a class="el" href="structburn__source.html#a7756a887e9dd87f4cfa928b781ae2f16">burn_source::read_xt</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *, unsigned char *buffer, int size)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This substitutes for (*read)() in versions above 0. </p>
</div>
</div>
<a class="anchor" id="ada75710f35fe822c592b37d01505609d"></a><!-- doxytag: member="burn_source::refcount" ref="ada75710f35fe822c592b37d01505609d" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int <a class="el" href="structburn__source.html#ada75710f35fe822c592b37d01505609d">burn_source::refcount</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Reference count for the data source. </p>
<p>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 <a class="el" href="libburn_8h.html#a1a03f8b3088b8ce6305e7a48c3e034eb" title="Free a burn_source (decrease its refcount and maybe free it).">burn_source_free()</a> to destroy your references to it. </p>
<p>Definition at line <a class="el" href="libburn_8h_source.html#l00402">402</a> of file <a class="el" href="libburn_8h_source.html">libburn.h</a>.</p>
</div>
</div>
<a class="anchor" id="a14da00d9e877e6d83ccdee7e8df00158"></a><!-- doxytag: member="burn_source::set_size" ref="a14da00d9e877e6d83ccdee7e8df00158" args=")(struct burn_source *source, off_t size)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int(* <a class="el" href="structburn__source.html#a14da00d9e877e6d83ccdee7e8df00158">burn_source::set_size</a>)(struct <a class="el" href="structburn__source.html">burn_source</a> *source, off_t size)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Program the reply of (*get_size) to a fixed value. </p>
<p>It is advised to implement this by a attribute off_t fixed_size; in *data . The <a class="el" href="structburn__source.html#a200c110bc2478463843b7779b8a25493" title="Read data from the source.">read()</a> 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.</p>
<p>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 <a class="el" href="libburn_8h.html#a587a8bb93d8b0a310923185239489fef" title="Sets a fixed track size after the data source object has already been created.">burn_track_set_size()</a> and possibly even padding might be left out. </p>
</div>
</div>
<a class="anchor" id="af7f96269792e56ee68c112f1e9e4027f"></a><!-- doxytag: member="burn_source::version" ref="af7f96269792e56ee68c112f1e9e4027f" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int <a class="el" href="structburn__source.html#af7f96269792e56ee68c112f1e9e4027f">burn_source::version</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Valid only if above member . </p>
<p>(*read)() is NULL. This indicates a version of struct <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a> younger than 0. From then on, member .version tells which further members exist in the memory layout of struct <a class="el" href="structburn__source.html" title="Data source interface for tracks.">burn_source</a>. libburn will only touch those announced extensions.</p>
<p>Versions: 0 has .(*read)() != NULL, not even .version is present. 1 has .version, .(*read_xt)(), .(*cancel)() </p>
<p>Definition at line <a class="el" href="libburn_8h_source.html#l00505">505</a> of file <a class="el" href="libburn_8h_source.html">libburn.h</a>.</p>
</div>
</div>
<hr/>The documentation for this struct was generated from the following file:<ul>
<li><a class="el" href="libburn_8h_source.html">libburn.h</a></li>
</ul>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 30 Sep 2009 for libburn by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
