<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> <title>FLAC: Porting from FLAC 1.1.2 to 1.1.3</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.4.2 --> <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="hierarchy.html">Class Hierarchy</a> | <a class="qindex" href="classes.html">Alphabetical List</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="dirs.html">Directories</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a> | <a class="qindex" href="globals.html">File Members</a></div> <h1>Porting from FLAC 1.1.2 to 1.1.3<br> <small> [<a class="el" href="group__porting.html">Porting Guide for New Versions</a>]</small> </h1>The main change between the APIs in 1.1.2 and 1.1.3 is that they have been simplified. First, libOggFLAC has been merged into libFLAC and libOggFLAC++ has been merged into libFLAC++. Second, both the three decoding layers and three encoding layers have been merged into a single stream decoder and stream encoder. That is, the functionality of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged into <a class="el" href="structFLAC____StreamDecoder.html">FLAC__StreamDecoder</a>, and FLAC__SeekableStreamEncoder and FLAC__FileEncoder into <a class="el" href="structFLAC____StreamEncoder.html">FLAC__StreamEncoder</a>. Only the <a class="el" href="structFLAC____StreamDecoder.html">FLAC__StreamDecoder</a> and <a class="el" href="structFLAC____StreamEncoder.html">FLAC__StreamEncoder</a> remain. What this means is there is now a single API that can be used to encode or decode streams to/from native FLAC or Ogg FLAC and the single API can work on both seekable and non-seekable streams.<p> Instead of creating an encoder or decoder of a certain layer, now the client will always create a <a class="el" href="structFLAC____StreamEncoder.html">FLAC__StreamEncoder</a> or <a class="el" href="structFLAC____StreamDecoder.html">FLAC__StreamDecoder</a>. The old layers are now differentiated by the initialization function. For example, for the decoder, FLAC__stream_decoder_init() has been replaced by <a class="el" href="group__flac__stream__decoder.html#ga36">FLAC__stream_decoder_init_stream()</a>. This init function takes callbacks for the I/O, and the seeking callbacks are optional. This allows the client to use the same object for seekable and non-seekable streams. For decoding a FLAC file directly, the client can use <a class="el" href="group__flac__stream__decoder.html#ga40">FLAC__stream_decoder_init_file()</a> and pass just a filename and fewer callbacks; most of the other callbacks are supplied internally. For situations where fopen()ing by filename is not possible (e.g. Unicode filenames on Windows) the client can instead open the file itself and supply the FILE* to <a class="el" href="group__flac__stream__decoder.html#ga38">FLAC__stream_decoder_init_FILE()</a>. The init functions now returns a FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState. Since the callbacks and client data are now passed to the init function, the FLAC__stream_decoder_set_*_callback() functions and FLAC__stream_decoder_set_client_data() are no longer needed. The rest of the calls to the decoder are the same as before.<p> There are counterpart init functions for Ogg FLAC, e.g. <a class="el" href="group__flac__stream__decoder.html#ga37">FLAC__stream_decoder_init_ogg_stream()</a>. All the rest of the calls and callbacks are the same as for native FLAC.<p> As an example, in FLAC 1.1.2 a seekable stream decoder would have been set up like so:<p> <div class="fragment"><pre class="fragment"> FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new(); <span class="keywordflow">if</span>(decoder == NULL) do_something; FLAC__seekable_stream_decoder_set_md5_checking(decoder, <span class="keyword">true</span>); [... other settings ...] FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback); FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback); FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback); FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback); FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback); FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback); FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback); FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback); FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data); <span class="keywordflow">if</span>(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something; </pre></div><p> In FLAC 1.1.3 it is like this:<p> <div class="fragment"><pre class="fragment"> <a class="code" href="structFLAC____StreamDecoder.html">FLAC__StreamDecoder</a> *decoder = <a class="code" href="group__flac__stream__decoder.html#ga16">FLAC__stream_decoder_new</a>(); <span class="keywordflow">if</span>(decoder == NULL) do_something; <a class="code" href="group__flac__stream__decoder.html#ga19">FLAC__stream_decoder_set_md5_checking</a>(decoder, <span class="keyword">true</span>); [... other settings ...] <span class="keywordflow">if</span>(<a class="code" href="group__flac__stream__decoder.html#ga36">FLAC__stream_decoder_init_stream</a>( decoder, my_read_callback, my_seek_callback, <span class="comment">// or NULL</span> my_tell_callback, <span class="comment">// or NULL</span> my_length_callback, <span class="comment">// or NULL</span> my_eof_callback, <span class="comment">// or NULL</span> my_write_callback, my_metadata_callback, <span class="comment">// or NULL</span> my_error_callback, my_client_data ) != <a class="code" href="group__flac__stream__decoder.html#gga51a26">FLAC__STREAM_DECODER_INIT_STATUS_OK</a>) do_something; </pre></div><p> or you could do;<p> <div class="fragment"><pre class="fragment"> [...] FILE *file = fopen(<span class="stringliteral">"somefile.flac"</span>,<span class="stringliteral">"rb"</span>); <span class="keywordflow">if</span>(file == NULL) do_somthing; <span class="keywordflow">if</span>(<a class="code" href="group__flac__stream__decoder.html#ga38">FLAC__stream_decoder_init_FILE</a>( decoder, file, my_write_callback, my_metadata_callback, <span class="comment">// or NULL</span> my_error_callback, my_client_data ) != <a class="code" href="group__flac__stream__decoder.html#gga51a26">FLAC__STREAM_DECODER_INIT_STATUS_OK</a>) do_something; </pre></div><p> or just:<p> <div class="fragment"><pre class="fragment"> [...] <span class="keywordflow">if</span>(<a class="code" href="group__flac__stream__decoder.html#ga40">FLAC__stream_decoder_init_file</a>( decoder, <span class="stringliteral">"somefile.flac"</span>, my_write_callback, my_metadata_callback, <span class="comment">// or NULL</span> my_error_callback, my_client_data ) != <a class="code" href="group__flac__stream__decoder.html#gga51a26">FLAC__STREAM_DECODER_INIT_STATUS_OK</a>) do_something; </pre></div><p> Another small change to the decoder is in how it handles unparseable streams. Before, when the decoder found an unparseable stream (reserved for when the decoder encounters a stream from a future encoder that it can't parse), it changed the state to <code>FLAC__STREAM_DECODER_UNPARSEABLE_STREAM</code>. Now the decoder instead drops sync and calls the error callback with a new error code <code>FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM</code>. This is more robust. If your error callback does not discriminate on the the error state, your code does not need to be changed.<p> The encoder now has a new setting: <a class="el" href="group__flac__stream__encoder.html#ga24">FLAC__stream_encoder_set_apodization()</a>. This is for setting the method used to window the data before LPC analysis. You only need to add a call to this function if the default is not suitable. There are also two new convenience functions that may be useful: <a class="el" href="group__flac__metadata__object.html#ga41">FLAC__metadata_object_cuesheet_calculate_cddb_id()</a> and <a class="el" href="group__flac__metadata__level0.html#ga2">FLAC__metadata_get_cuesheet()</a>.<p> The <em>bytes</em> parameter to FLAC__StreamDecoderReadCallback, FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback is now <code>size_t</code> instead of <code>unsigned</code>. <p> <table border="0" cellpadding="0" cellspacing="0"> <tr><td></td></tr> </table> <hr size="1"> <div class="copyright"> <!-- @@@ oh so hacky --> <table> <tr> <td align="left"> Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007 Josh Coalson </td> <td width="1%" align="right"> <a href="http://sourceforge.net"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=13478&type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" /></a> </td> </tr> </table> </div> <!-- Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007 Josh Coalson --> <!-- Permission is granted to copy, distribute and/or modify this document --> <!-- under the terms of the GNU Free Documentation License, Version 1.1 --> <!-- or any later version published by the Free Software Foundation; --> <!-- with no invariant sections. --> <!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html --> </body> </html>
