Moved external libraries into the "external" directory and added x64 build configuration.
authorSam Lantinga <slouken@libsdl.org>
Mon, 09 Jan 2012 04:20:54 -0500
changeset 5562686e67b59fd
parent 555 b92bfb451700
child 557 a55168d8babe
Moved external libraries into the "external" directory and added x64 build configuration.
VisualC/SDL_mixer.sln
VisualC/SDL_mixer.vcproj
VisualC/external/include/FLAC/all.h
VisualC/external/include/FLAC/assert.h
VisualC/external/include/FLAC/callback.h
VisualC/external/include/FLAC/export.h
VisualC/external/include/FLAC/format.h
VisualC/external/include/FLAC/metadata.h
VisualC/external/include/FLAC/ordinals.h
VisualC/external/include/FLAC/stream_decoder.h
VisualC/external/include/FLAC/stream_encoder.h
VisualC/external/include/MPEGfilter.h
VisualC/external/include/mikmod.h
VisualC/external/include/ogg/config_types.h
VisualC/external/include/ogg/ogg.h
VisualC/external/include/ogg/os_types.h
VisualC/external/include/smpeg.h
VisualC/external/include/vorbis/codec.h
VisualC/external/include/vorbis/vorbisfile.h
VisualC/external/lib/x64/LICENSE.FLAC.txt
VisualC/external/lib/x64/LICENSE.mikmod.txt
VisualC/external/lib/x64/LICENSE.ogg-vorbis.txt
VisualC/external/lib/x64/LICENSE.smpeg.txt
VisualC/external/lib/x64/libFLAC-8.dll
VisualC/external/lib/x64/libmikmod-2.dll
VisualC/external/lib/x64/libogg-0.dll
VisualC/external/lib/x64/libvorbis-0.dll
VisualC/external/lib/x64/libvorbisfile-3.dll
VisualC/external/lib/x64/smpeg.dll
VisualC/external/lib/x86/LICENSE.FLAC.txt
VisualC/external/lib/x86/LICENSE.mikmod.txt
VisualC/external/lib/x86/LICENSE.ogg-vorbis.txt
VisualC/external/lib/x86/LICENSE.smpeg.txt
VisualC/external/lib/x86/libFLAC-8.dll
VisualC/external/lib/x86/libmikmod-2.dll
VisualC/external/lib/x86/libogg-0.dll
VisualC/external/lib/x86/libvorbis-0.dll
VisualC/external/lib/x86/libvorbisfile-3.dll
VisualC/external/lib/x86/smpeg.dll
VisualC/flac/include/FLAC/all.h
VisualC/flac/include/FLAC/assert.h
VisualC/flac/include/FLAC/callback.h
VisualC/flac/include/FLAC/export.h
VisualC/flac/include/FLAC/format.h
VisualC/flac/include/FLAC/metadata.h
VisualC/flac/include/FLAC/ordinals.h
VisualC/flac/include/FLAC/stream_decoder.h
VisualC/flac/include/FLAC/stream_encoder.h
VisualC/flac/lib/LICENSE.FLAC.txt
VisualC/flac/lib/libFLAC-8.dll
VisualC/mikmod/include/mikmod.h
VisualC/mikmod/lib/LICENSE.mikmod.txt
VisualC/mikmod/lib/mikmod.dll
VisualC/native_midi/native_midi.vcproj
VisualC/playmus/playmus.vcproj
VisualC/playwave/playwave.vcproj
VisualC/smpeg/include/MPEGfilter.h
VisualC/smpeg/include/smpeg.h
VisualC/smpeg/lib/LICENSE.smpeg.txt
VisualC/smpeg/lib/smpeg.dll
VisualC/timidity/timidity.vcproj
VisualC/vorbis/include/ogg/config_types.h
VisualC/vorbis/include/ogg/ogg.h
VisualC/vorbis/include/ogg/os_types.h
VisualC/vorbis/include/vorbis/codec.h
VisualC/vorbis/include/vorbis/vorbisfile.h
VisualC/vorbis/lib/LICENSE.ogg-vorbis.txt
VisualC/vorbis/lib/libogg-0.dll
VisualC/vorbis/lib/libvorbis-0.dll
VisualC/vorbis/lib/libvorbisfile-3.dll
configure
configure.in
     1.1 --- a/VisualC/SDL_mixer.sln	Mon Jan 09 01:58:40 2012 -0500
     1.2 +++ b/VisualC/SDL_mixer.sln	Mon Jan 09 04:20:54 2012 -0500
     1.3 @@ -24,29 +24,51 @@
     1.4  Global
     1.5  	GlobalSection(SolutionConfigurationPlatforms) = preSolution
     1.6  		Debug|Win32 = Debug|Win32
     1.7 +		Debug|x64 = Debug|x64
     1.8  		Release|Win32 = Release|Win32
     1.9 +		Release|x64 = Release|x64
    1.10  	EndGlobalSection
    1.11  	GlobalSection(ProjectConfigurationPlatforms) = postSolution
    1.12  		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Debug|Win32.ActiveCfg = Debug|Win32
    1.13  		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Debug|Win32.Build.0 = Debug|Win32
    1.14 +		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Debug|x64.ActiveCfg = Debug|x64
    1.15 +		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Debug|x64.Build.0 = Debug|x64
    1.16  		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Release|Win32.ActiveCfg = Release|Win32
    1.17  		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Release|Win32.Build.0 = Release|Win32
    1.18 +		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Release|x64.ActiveCfg = Release|x64
    1.19 +		{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}.Release|x64.Build.0 = Release|x64
    1.20  		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Debug|Win32.ActiveCfg = Debug|Win32
    1.21  		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Debug|Win32.Build.0 = Debug|Win32
    1.22 +		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Debug|x64.ActiveCfg = Debug|x64
    1.23 +		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Debug|x64.Build.0 = Debug|x64
    1.24  		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Release|Win32.ActiveCfg = Release|Win32
    1.25  		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Release|Win32.Build.0 = Release|Win32
    1.26 +		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Release|x64.ActiveCfg = Release|x64
    1.27 +		{EBDA67CA-4A23-4F22-BFBC-B8DBE0580D4F}.Release|x64.Build.0 = Release|x64
    1.28  		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Debug|Win32.ActiveCfg = Debug|Win32
    1.29  		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Debug|Win32.Build.0 = Debug|Win32
    1.30 +		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Debug|x64.ActiveCfg = Debug|x64
    1.31 +		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Debug|x64.Build.0 = Debug|x64
    1.32  		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Release|Win32.ActiveCfg = Release|Win32
    1.33  		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Release|Win32.Build.0 = Release|Win32
    1.34 +		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Release|x64.ActiveCfg = Release|x64
    1.35 +		{72CB0DD4-051D-486C-9CB3-75FE16F7D87A}.Release|x64.Build.0 = Release|x64
    1.36  		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Debug|Win32.ActiveCfg = Debug|Win32
    1.37  		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Debug|Win32.Build.0 = Debug|Win32
    1.38 +		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Debug|x64.ActiveCfg = Debug|x64
    1.39 +		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Debug|x64.Build.0 = Debug|x64
    1.40  		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Release|Win32.ActiveCfg = Release|Win32
    1.41  		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Release|Win32.Build.0 = Release|Win32
    1.42 +		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Release|x64.ActiveCfg = Release|x64
    1.43 +		{AC86CEAA-9908-476F-B15F-C7193CEF81BD}.Release|x64.Build.0 = Release|x64
    1.44  		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Debug|Win32.ActiveCfg = Debug|Win32
    1.45  		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Debug|Win32.Build.0 = Debug|Win32
    1.46 +		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Debug|x64.ActiveCfg = Debug|x64
    1.47 +		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Debug|x64.Build.0 = Debug|x64
    1.48  		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Release|Win32.ActiveCfg = Release|Win32
    1.49  		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Release|Win32.Build.0 = Release|Win32
    1.50 +		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Release|x64.ActiveCfg = Release|x64
    1.51 +		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}.Release|x64.Build.0 = Release|x64
    1.52  	EndGlobalSection
    1.53  	GlobalSection(SolutionProperties) = preSolution
    1.54  		HideSolutionNode = FALSE
     2.1 --- a/VisualC/SDL_mixer.vcproj	Mon Jan 09 01:58:40 2012 -0500
     2.2 +++ b/VisualC/SDL_mixer.vcproj	Mon Jan 09 04:20:54 2012 -0500
     2.3 @@ -11,6 +11,9 @@
     2.4  		<Platform
     2.5  			Name="Win32"
     2.6  		/>
     2.7 +		<Platform
     2.8 +			Name="x64"
     2.9 +		/>
    2.10  	</Platforms>
    2.11  	<ToolFiles>
    2.12  	</ToolFiles>
    2.13 @@ -49,14 +52,11 @@
    2.14  				Name="VCCLCompilerTool"
    2.15  				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
    2.16  				Optimization="0"
    2.17 -				AdditionalIncludeDirectories="..\timidity;..\native_midi;flac\include;mikmod\include;smpeg\include;vorbis\include"
    2.18 -				PreprocessorDefinitions="_DEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;mikmod.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
    2.19 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;external\include"
    2.20 +				PreprocessorDefinitions="_DEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;libmikmod-2.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
    2.21  				MinimalRebuild="true"
    2.22  				RuntimeLibrary="2"
    2.23  				PrecompiledHeaderFile=".\Debug/SDL_mixer.pch"
    2.24 -				AssemblerListingLocation=".\Debug/"
    2.25 -				ObjectFile=".\Debug/"
    2.26 -				ProgramDataBaseFileName=".\Debug/"
    2.27  				WarningLevel="3"
    2.28  				SuppressStartupBanner="true"
    2.29  				DebugInformationFormat="4"
    2.30 @@ -75,9 +75,7 @@
    2.31  			<Tool
    2.32  				Name="VCLinkerTool"
    2.33  				AdditionalDependencies="winmm.lib SDL.lib"
    2.34 -				OutputFile=".\Debug/SDL_mixer.dll"
    2.35  				LinkIncremental="2"
    2.36 -				SuppressStartupBanner="true"
    2.37  				GenerateDebugInformation="true"
    2.38  				ProgramDatabaseFile=".\Debug/SDL_mixer.pdb"
    2.39  				SubSystem="2"
    2.40 @@ -145,17 +143,13 @@
    2.41  				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
    2.42  				Optimization="2"
    2.43  				InlineFunctionExpansion="1"
    2.44 -				AdditionalIncludeDirectories="..\timidity;..\native_midi;flac\include;mikmod\include;smpeg\include;vorbis\include"
    2.45 -				PreprocessorDefinitions="NDEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;mikmod.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
    2.46 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;external\include"
    2.47 +				PreprocessorDefinitions="NDEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;libmikmod-2.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
    2.48  				StringPooling="true"
    2.49  				RuntimeLibrary="2"
    2.50  				EnableFunctionLevelLinking="true"
    2.51  				PrecompiledHeaderFile=".\Release/SDL_mixer.pch"
    2.52 -				AssemblerListingLocation=".\Release/"
    2.53 -				ObjectFile=".\Release/"
    2.54 -				ProgramDataBaseFileName=".\Release/"
    2.55  				WarningLevel="3"
    2.56 -				SuppressStartupBanner="true"
    2.57  			/>
    2.58  			<Tool
    2.59  				Name="VCManagedResourceCompilerTool"
    2.60 @@ -171,9 +165,7 @@
    2.61  			<Tool
    2.62  				Name="VCLinkerTool"
    2.63  				AdditionalDependencies="winmm.lib SDL.lib"
    2.64 -				OutputFile=".\Release/SDL_mixer.dll"
    2.65  				LinkIncremental="1"
    2.66 -				SuppressStartupBanner="true"
    2.67  				ProgramDatabaseFile=".\Release/SDL_mixer.pdb"
    2.68  				SubSystem="2"
    2.69  				RandomizedBaseAddress="1"
    2.70 @@ -205,6 +197,185 @@
    2.71  				Name="VCPostBuildEventTool"
    2.72  			/>
    2.73  		</Configuration>
    2.74 +		<Configuration
    2.75 +			Name="Debug|x64"
    2.76 +			OutputDirectory="$(PlatformName)\$(ConfigurationName)"
    2.77 +			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)"
    2.78 +			ConfigurationType="2"
    2.79 +			InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
    2.80 +			UseOfMFC="0"
    2.81 +			ATLMinimizesCRunTimeLibraryUsage="false"
    2.82 +			>
    2.83 +			<Tool
    2.84 +				Name="VCPreBuildEventTool"
    2.85 +			/>
    2.86 +			<Tool
    2.87 +				Name="VCCustomBuildTool"
    2.88 +			/>
    2.89 +			<Tool
    2.90 +				Name="VCXMLDataGeneratorTool"
    2.91 +			/>
    2.92 +			<Tool
    2.93 +				Name="VCWebServiceProxyGeneratorTool"
    2.94 +			/>
    2.95 +			<Tool
    2.96 +				Name="VCMIDLTool"
    2.97 +				PreprocessorDefinitions="_DEBUG"
    2.98 +				MkTypLibCompatible="true"
    2.99 +				SuppressStartupBanner="true"
   2.100 +				TargetEnvironment="3"
   2.101 +				TypeLibraryName=".\Debug/SDL_mixer.tlb"
   2.102 +				HeaderFileName=""
   2.103 +			/>
   2.104 +			<Tool
   2.105 +				Name="VCCLCompilerTool"
   2.106 +				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
   2.107 +				Optimization="0"
   2.108 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;external\include"
   2.109 +				PreprocessorDefinitions="_DEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;libmikmod-2.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
   2.110 +				MinimalRebuild="true"
   2.111 +				RuntimeLibrary="2"
   2.112 +				PrecompiledHeaderFile=".\Debug/SDL_mixer.pch"
   2.113 +				WarningLevel="3"
   2.114 +				SuppressStartupBanner="true"
   2.115 +				DebugInformationFormat="3"
   2.116 +			/>
   2.117 +			<Tool
   2.118 +				Name="VCManagedResourceCompilerTool"
   2.119 +			/>
   2.120 +			<Tool
   2.121 +				Name="VCResourceCompilerTool"
   2.122 +				PreprocessorDefinitions="_DEBUG"
   2.123 +				Culture="1033"
   2.124 +			/>
   2.125 +			<Tool
   2.126 +				Name="VCPreLinkEventTool"
   2.127 +			/>
   2.128 +			<Tool
   2.129 +				Name="VCLinkerTool"
   2.130 +				AdditionalDependencies="winmm.lib SDL.lib"
   2.131 +				LinkIncremental="2"
   2.132 +				GenerateDebugInformation="true"
   2.133 +				ProgramDatabaseFile=".\Debug/SDL_mixer.pdb"
   2.134 +				SubSystem="2"
   2.135 +				RandomizedBaseAddress="1"
   2.136 +				DataExecutionPrevention="0"
   2.137 +				ImportLibrary=".\Debug/SDL_mixer.lib"
   2.138 +				TargetMachine="17"
   2.139 +			/>
   2.140 +			<Tool
   2.141 +				Name="VCALinkTool"
   2.142 +			/>
   2.143 +			<Tool
   2.144 +				Name="VCManifestTool"
   2.145 +			/>
   2.146 +			<Tool
   2.147 +				Name="VCXDCMakeTool"
   2.148 +			/>
   2.149 +			<Tool
   2.150 +				Name="VCBscMakeTool"
   2.151 +				SuppressStartupBanner="true"
   2.152 +				OutputFile=".\Debug/SDL_mixer.bsc"
   2.153 +			/>
   2.154 +			<Tool
   2.155 +				Name="VCFxCopTool"
   2.156 +			/>
   2.157 +			<Tool
   2.158 +				Name="VCAppVerifierTool"
   2.159 +			/>
   2.160 +			<Tool
   2.161 +				Name="VCPostBuildEventTool"
   2.162 +			/>
   2.163 +		</Configuration>
   2.164 +		<Configuration
   2.165 +			Name="Release|x64"
   2.166 +			OutputDirectory="$(PlatformName)\$(ConfigurationName)"
   2.167 +			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)"
   2.168 +			ConfigurationType="2"
   2.169 +			InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
   2.170 +			UseOfMFC="0"
   2.171 +			ATLMinimizesCRunTimeLibraryUsage="false"
   2.172 +			>
   2.173 +			<Tool
   2.174 +				Name="VCPreBuildEventTool"
   2.175 +			/>
   2.176 +			<Tool
   2.177 +				Name="VCCustomBuildTool"
   2.178 +			/>
   2.179 +			<Tool
   2.180 +				Name="VCXMLDataGeneratorTool"
   2.181 +			/>
   2.182 +			<Tool
   2.183 +				Name="VCWebServiceProxyGeneratorTool"
   2.184 +			/>
   2.185 +			<Tool
   2.186 +				Name="VCMIDLTool"
   2.187 +				PreprocessorDefinitions="NDEBUG"
   2.188 +				MkTypLibCompatible="true"
   2.189 +				SuppressStartupBanner="true"
   2.190 +				TargetEnvironment="3"
   2.191 +				TypeLibraryName=".\Release/SDL_mixer.tlb"
   2.192 +				HeaderFileName=""
   2.193 +			/>
   2.194 +			<Tool
   2.195 +				Name="VCCLCompilerTool"
   2.196 +				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
   2.197 +				Optimization="2"
   2.198 +				InlineFunctionExpansion="1"
   2.199 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;external\include"
   2.200 +				PreprocessorDefinitions="NDEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;libmikmod-2.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;FLAC_MUSIC;FLAC_DYNAMIC=\&quot;libFLAC-8.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI"
   2.201 +				StringPooling="true"
   2.202 +				RuntimeLibrary="2"
   2.203 +				EnableFunctionLevelLinking="true"
   2.204 +				PrecompiledHeaderFile=".\Release/SDL_mixer.pch"
   2.205 +				WarningLevel="3"
   2.206 +			/>
   2.207 +			<Tool
   2.208 +				Name="VCManagedResourceCompilerTool"
   2.209 +			/>
   2.210 +			<Tool
   2.211 +				Name="VCResourceCompilerTool"
   2.212 +				PreprocessorDefinitions="NDEBUG"
   2.213 +				Culture="1033"
   2.214 +			/>
   2.215 +			<Tool
   2.216 +				Name="VCPreLinkEventTool"
   2.217 +			/>
   2.218 +			<Tool
   2.219 +				Name="VCLinkerTool"
   2.220 +				AdditionalDependencies="winmm.lib SDL.lib"
   2.221 +				LinkIncremental="1"
   2.222 +				ProgramDatabaseFile=".\Release/SDL_mixer.pdb"
   2.223 +				SubSystem="2"
   2.224 +				RandomizedBaseAddress="1"
   2.225 +				DataExecutionPrevention="0"
   2.226 +				ImportLibrary=".\Release/SDL_mixer.lib"
   2.227 +				TargetMachine="17"
   2.228 +			/>
   2.229 +			<Tool
   2.230 +				Name="VCALinkTool"
   2.231 +			/>
   2.232 +			<Tool
   2.233 +				Name="VCManifestTool"
   2.234 +			/>
   2.235 +			<Tool
   2.236 +				Name="VCXDCMakeTool"
   2.237 +			/>
   2.238 +			<Tool
   2.239 +				Name="VCBscMakeTool"
   2.240 +				SuppressStartupBanner="true"
   2.241 +				OutputFile=".\Release/SDL_mixer.bsc"
   2.242 +			/>
   2.243 +			<Tool
   2.244 +				Name="VCFxCopTool"
   2.245 +			/>
   2.246 +			<Tool
   2.247 +				Name="VCAppVerifierTool"
   2.248 +			/>
   2.249 +			<Tool
   2.250 +				Name="VCPostBuildEventTool"
   2.251 +			/>
   2.252 +		</Configuration>
   2.253  	</Configurations>
   2.254  	<References>
   2.255  	</References>
   2.256 @@ -254,6 +425,24 @@
   2.257  					PreprocessorDefinitions=""
   2.258  				/>
   2.259  			</FileConfiguration>
   2.260 +			<FileConfiguration
   2.261 +				Name="Debug|x64"
   2.262 +				>
   2.263 +				<Tool
   2.264 +					Name="VCCLCompilerTool"
   2.265 +					AdditionalIncludeDirectories=""
   2.266 +					PreprocessorDefinitions=""
   2.267 +				/>
   2.268 +			</FileConfiguration>
   2.269 +			<FileConfiguration
   2.270 +				Name="Release|x64"
   2.271 +				>
   2.272 +				<Tool
   2.273 +					Name="VCCLCompilerTool"
   2.274 +					AdditionalIncludeDirectories=""
   2.275 +					PreprocessorDefinitions=""
   2.276 +				/>
   2.277 +			</FileConfiguration>
   2.278  		</File>
   2.279  		<File
   2.280  			RelativePath="..\dynamic_mp3.h"
   2.281 @@ -280,6 +469,24 @@
   2.282  					PreprocessorDefinitions=""
   2.283  				/>
   2.284  			</FileConfiguration>
   2.285 +			<FileConfiguration
   2.286 +				Name="Debug|x64"
   2.287 +				>
   2.288 +				<Tool
   2.289 +					Name="VCCLCompilerTool"
   2.290 +					AdditionalIncludeDirectories=""
   2.291 +					PreprocessorDefinitions=""
   2.292 +				/>
   2.293 +			</FileConfiguration>
   2.294 +			<FileConfiguration
   2.295 +				Name="Release|x64"
   2.296 +				>
   2.297 +				<Tool
   2.298 +					Name="VCCLCompilerTool"
   2.299 +					AdditionalIncludeDirectories=""
   2.300 +					PreprocessorDefinitions=""
   2.301 +				/>
   2.302 +			</FileConfiguration>
   2.303  		</File>
   2.304  		<File
   2.305  			RelativePath="..\dynamic_ogg.h"
   2.306 @@ -306,6 +513,24 @@
   2.307  					PreprocessorDefinitions=""
   2.308  				/>
   2.309  			</FileConfiguration>
   2.310 +			<FileConfiguration
   2.311 +				Name="Debug|x64"
   2.312 +				>
   2.313 +				<Tool
   2.314 +					Name="VCCLCompilerTool"
   2.315 +					AdditionalIncludeDirectories=""
   2.316 +					PreprocessorDefinitions=""
   2.317 +				/>
   2.318 +			</FileConfiguration>
   2.319 +			<FileConfiguration
   2.320 +				Name="Release|x64"
   2.321 +				>
   2.322 +				<Tool
   2.323 +					Name="VCCLCompilerTool"
   2.324 +					AdditionalIncludeDirectories=""
   2.325 +					PreprocessorDefinitions=""
   2.326 +				/>
   2.327 +			</FileConfiguration>
   2.328  		</File>
   2.329  		<File
   2.330  			RelativePath="..\effect_stereoreverse.c"
   2.331 @@ -328,6 +553,24 @@
   2.332  					PreprocessorDefinitions=""
   2.333  				/>
   2.334  			</FileConfiguration>
   2.335 +			<FileConfiguration
   2.336 +				Name="Debug|x64"
   2.337 +				>
   2.338 +				<Tool
   2.339 +					Name="VCCLCompilerTool"
   2.340 +					AdditionalIncludeDirectories=""
   2.341 +					PreprocessorDefinitions=""
   2.342 +				/>
   2.343 +			</FileConfiguration>
   2.344 +			<FileConfiguration
   2.345 +				Name="Release|x64"
   2.346 +				>
   2.347 +				<Tool
   2.348 +					Name="VCCLCompilerTool"
   2.349 +					AdditionalIncludeDirectories=""
   2.350 +					PreprocessorDefinitions=""
   2.351 +				/>
   2.352 +			</FileConfiguration>
   2.353  		</File>
   2.354  		<File
   2.355  			RelativePath="..\effects_internal.c"
   2.356 @@ -350,6 +593,24 @@
   2.357  					PreprocessorDefinitions=""
   2.358  				/>
   2.359  			</FileConfiguration>
   2.360 +			<FileConfiguration
   2.361 +				Name="Debug|x64"
   2.362 +				>
   2.363 +				<Tool
   2.364 +					Name="VCCLCompilerTool"
   2.365 +					AdditionalIncludeDirectories=""
   2.366 +					PreprocessorDefinitions=""
   2.367 +				/>
   2.368 +			</FileConfiguration>
   2.369 +			<FileConfiguration
   2.370 +				Name="Release|x64"
   2.371 +				>
   2.372 +				<Tool
   2.373 +					Name="VCCLCompilerTool"
   2.374 +					AdditionalIncludeDirectories=""
   2.375 +					PreprocessorDefinitions=""
   2.376 +				/>
   2.377 +			</FileConfiguration>
   2.378  		</File>
   2.379  		<File
   2.380  			RelativePath="..\effects_internal.h"
   2.381 @@ -384,6 +645,24 @@
   2.382  					PreprocessorDefinitions=""
   2.383  				/>
   2.384  			</FileConfiguration>
   2.385 +			<FileConfiguration
   2.386 +				Name="Debug|x64"
   2.387 +				>
   2.388 +				<Tool
   2.389 +					Name="VCCLCompilerTool"
   2.390 +					AdditionalIncludeDirectories=""
   2.391 +					PreprocessorDefinitions=""
   2.392 +				/>
   2.393 +			</FileConfiguration>
   2.394 +			<FileConfiguration
   2.395 +				Name="Release|x64"
   2.396 +				>
   2.397 +				<Tool
   2.398 +					Name="VCCLCompilerTool"
   2.399 +					AdditionalIncludeDirectories=""
   2.400 +					PreprocessorDefinitions=""
   2.401 +				/>
   2.402 +			</FileConfiguration>
   2.403  		</File>
   2.404  		<File
   2.405  			RelativePath="..\load_aiff.h"
   2.406 @@ -418,6 +697,24 @@
   2.407  					PreprocessorDefinitions=""
   2.408  				/>
   2.409  			</FileConfiguration>
   2.410 +			<FileConfiguration
   2.411 +				Name="Debug|x64"
   2.412 +				>
   2.413 +				<Tool
   2.414 +					Name="VCCLCompilerTool"
   2.415 +					AdditionalIncludeDirectories=""
   2.416 +					PreprocessorDefinitions=""
   2.417 +				/>
   2.418 +			</FileConfiguration>
   2.419 +			<FileConfiguration
   2.420 +				Name="Release|x64"
   2.421 +				>
   2.422 +				<Tool
   2.423 +					Name="VCCLCompilerTool"
   2.424 +					AdditionalIncludeDirectories=""
   2.425 +					PreprocessorDefinitions=""
   2.426 +				/>
   2.427 +			</FileConfiguration>
   2.428  		</File>
   2.429  		<File
   2.430  			RelativePath="..\load_ogg.h"
   2.431 @@ -444,6 +741,24 @@
   2.432  					PreprocessorDefinitions=""
   2.433  				/>
   2.434  			</FileConfiguration>
   2.435 +			<FileConfiguration
   2.436 +				Name="Debug|x64"
   2.437 +				>
   2.438 +				<Tool
   2.439 +					Name="VCCLCompilerTool"
   2.440 +					AdditionalIncludeDirectories=""
   2.441 +					PreprocessorDefinitions=""
   2.442 +				/>
   2.443 +			</FileConfiguration>
   2.444 +			<FileConfiguration
   2.445 +				Name="Release|x64"
   2.446 +				>
   2.447 +				<Tool
   2.448 +					Name="VCCLCompilerTool"
   2.449 +					AdditionalIncludeDirectories=""
   2.450 +					PreprocessorDefinitions=""
   2.451 +				/>
   2.452 +			</FileConfiguration>
   2.453  		</File>
   2.454  		<File
   2.455  			RelativePath="..\load_voc.h"
   2.456 @@ -470,6 +785,24 @@
   2.457  					PreprocessorDefinitions=""
   2.458  				/>
   2.459  			</FileConfiguration>
   2.460 +			<FileConfiguration
   2.461 +				Name="Debug|x64"
   2.462 +				>
   2.463 +				<Tool
   2.464 +					Name="VCCLCompilerTool"
   2.465 +					AdditionalIncludeDirectories=""
   2.466 +					PreprocessorDefinitions=""
   2.467 +				/>
   2.468 +			</FileConfiguration>
   2.469 +			<FileConfiguration
   2.470 +				Name="Release|x64"
   2.471 +				>
   2.472 +				<Tool
   2.473 +					Name="VCCLCompilerTool"
   2.474 +					AdditionalIncludeDirectories=""
   2.475 +					PreprocessorDefinitions=""
   2.476 +				/>
   2.477 +			</FileConfiguration>
   2.478  		</File>
   2.479  		<File
   2.480  			RelativePath="..\music.c"
   2.481 @@ -492,6 +825,24 @@
   2.482  					PreprocessorDefinitions=""
   2.483  				/>
   2.484  			</FileConfiguration>
   2.485 +			<FileConfiguration
   2.486 +				Name="Debug|x64"
   2.487 +				>
   2.488 +				<Tool
   2.489 +					Name="VCCLCompilerTool"
   2.490 +					AdditionalIncludeDirectories=""
   2.491 +					PreprocessorDefinitions=""
   2.492 +				/>
   2.493 +			</FileConfiguration>
   2.494 +			<FileConfiguration
   2.495 +				Name="Release|x64"
   2.496 +				>
   2.497 +				<Tool
   2.498 +					Name="VCCLCompilerTool"
   2.499 +					AdditionalIncludeDirectories=""
   2.500 +					PreprocessorDefinitions=""
   2.501 +				/>
   2.502 +			</FileConfiguration>
   2.503  		</File>
   2.504  		<File
   2.505  			RelativePath="..\music_cmd.c"
   2.506 @@ -514,6 +865,24 @@
   2.507  					PreprocessorDefinitions=""
   2.508  				/>
   2.509  			</FileConfiguration>
   2.510 +			<FileConfiguration
   2.511 +				Name="Debug|x64"
   2.512 +				>
   2.513 +				<Tool
   2.514 +					Name="VCCLCompilerTool"
   2.515 +					AdditionalIncludeDirectories=""
   2.516 +					PreprocessorDefinitions=""
   2.517 +				/>
   2.518 +			</FileConfiguration>
   2.519 +			<FileConfiguration
   2.520 +				Name="Release|x64"
   2.521 +				>
   2.522 +				<Tool
   2.523 +					Name="VCCLCompilerTool"
   2.524 +					AdditionalIncludeDirectories=""
   2.525 +					PreprocessorDefinitions=""
   2.526 +				/>
   2.527 +			</FileConfiguration>
   2.528  		</File>
   2.529  		<File
   2.530  			RelativePath="..\music_cmd.h"
   2.531 @@ -564,6 +933,24 @@
   2.532  					PreprocessorDefinitions=""
   2.533  				/>
   2.534  			</FileConfiguration>
   2.535 +			<FileConfiguration
   2.536 +				Name="Debug|x64"
   2.537 +				>
   2.538 +				<Tool
   2.539 +					Name="VCCLCompilerTool"
   2.540 +					AdditionalIncludeDirectories=""
   2.541 +					PreprocessorDefinitions=""
   2.542 +				/>
   2.543 +			</FileConfiguration>
   2.544 +			<FileConfiguration
   2.545 +				Name="Release|x64"
   2.546 +				>
   2.547 +				<Tool
   2.548 +					Name="VCCLCompilerTool"
   2.549 +					AdditionalIncludeDirectories=""
   2.550 +					PreprocessorDefinitions=""
   2.551 +				/>
   2.552 +			</FileConfiguration>
   2.553  		</File>
   2.554  		<File
   2.555  			RelativePath="..\music_ogg.h"
   2.556 @@ -592,6 +979,22 @@
   2.557  					PreprocessorDefinitions=""
   2.558  				/>
   2.559  			</FileConfiguration>
   2.560 +			<FileConfiguration
   2.561 +				Name="Debug|x64"
   2.562 +				>
   2.563 +				<Tool
   2.564 +					Name="VCResourceCompilerTool"
   2.565 +					PreprocessorDefinitions=""
   2.566 +				/>
   2.567 +			</FileConfiguration>
   2.568 +			<FileConfiguration
   2.569 +				Name="Release|x64"
   2.570 +				>
   2.571 +				<Tool
   2.572 +					Name="VCResourceCompilerTool"
   2.573 +					PreprocessorDefinitions=""
   2.574 +				/>
   2.575 +			</FileConfiguration>
   2.576  		</File>
   2.577  		<File
   2.578  			RelativePath="..\wavestream.c"
   2.579 @@ -614,6 +1017,24 @@
   2.580  					PreprocessorDefinitions=""
   2.581  				/>
   2.582  			</FileConfiguration>
   2.583 +			<FileConfiguration
   2.584 +				Name="Debug|x64"
   2.585 +				>
   2.586 +				<Tool
   2.587 +					Name="VCCLCompilerTool"
   2.588 +					AdditionalIncludeDirectories=""
   2.589 +					PreprocessorDefinitions=""
   2.590 +				/>
   2.591 +			</FileConfiguration>
   2.592 +			<FileConfiguration
   2.593 +				Name="Release|x64"
   2.594 +				>
   2.595 +				<Tool
   2.596 +					Name="VCCLCompilerTool"
   2.597 +					AdditionalIncludeDirectories=""
   2.598 +					PreprocessorDefinitions=""
   2.599 +				/>
   2.600 +			</FileConfiguration>
   2.601  		</File>
   2.602  		<File
   2.603  			RelativePath="..\wavestream.h"
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/VisualC/external/include/FLAC/all.h	Mon Jan 09 04:20:54 2012 -0500
     3.3 @@ -0,0 +1,370 @@
     3.4 +/* libFLAC - Free Lossless Audio Codec library
     3.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     3.6 + *
     3.7 + * Redistribution and use in source and binary forms, with or without
     3.8 + * modification, are permitted provided that the following conditions
     3.9 + * are met:
    3.10 + *
    3.11 + * - Redistributions of source code must retain the above copyright
    3.12 + * notice, this list of conditions and the following disclaimer.
    3.13 + *
    3.14 + * - Redistributions in binary form must reproduce the above copyright
    3.15 + * notice, this list of conditions and the following disclaimer in the
    3.16 + * documentation and/or other materials provided with the distribution.
    3.17 + *
    3.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    3.19 + * contributors may be used to endorse or promote products derived from
    3.20 + * this software without specific prior written permission.
    3.21 + *
    3.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    3.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    3.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    3.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    3.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    3.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    3.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    3.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    3.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    3.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    3.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    3.33 + */
    3.34 +
    3.35 +#ifndef FLAC__ALL_H
    3.36 +#define FLAC__ALL_H
    3.37 +
    3.38 +#include "export.h"
    3.39 +
    3.40 +#include "assert.h"
    3.41 +#include "callback.h"
    3.42 +#include "format.h"
    3.43 +#include "metadata.h"
    3.44 +#include "ordinals.h"
    3.45 +#include "stream_decoder.h"
    3.46 +#include "stream_encoder.h"
    3.47 +
    3.48 +/** \mainpage
    3.49 + *
    3.50 + * \section intro Introduction
    3.51 + *
    3.52 + * This is the documentation for the FLAC C and C++ APIs.  It is
    3.53 + * highly interconnected; this introduction should give you a top
    3.54 + * level idea of the structure and how to find the information you
    3.55 + * need.  As a prerequisite you should have at least a basic
    3.56 + * knowledge of the FLAC format, documented
    3.57 + * <A HREF="../format.html">here</A>.
    3.58 + *
    3.59 + * \section c_api FLAC C API
    3.60 + *
    3.61 + * The FLAC C API is the interface to libFLAC, a set of structures
    3.62 + * describing the components of FLAC streams, and functions for
    3.63 + * encoding and decoding streams, as well as manipulating FLAC
    3.64 + * metadata in files.  The public include files will be installed
    3.65 + * in your include area (for example /usr/include/FLAC/...).
    3.66 + *
    3.67 + * By writing a little code and linking against libFLAC, it is
    3.68 + * relatively easy to add FLAC support to another program.  The
    3.69 + * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
    3.70 + * Complete source code of libFLAC as well as the command-line
    3.71 + * encoder and plugins is available and is a useful source of
    3.72 + * examples.
    3.73 + *
    3.74 + * Aside from encoders and decoders, libFLAC provides a powerful
    3.75 + * metadata interface for manipulating metadata in FLAC files.  It
    3.76 + * allows the user to add, delete, and modify FLAC metadata blocks
    3.77 + * and it can automatically take advantage of PADDING blocks to avoid
    3.78 + * rewriting the entire FLAC file when changing the size of the
    3.79 + * metadata.
    3.80 + *
    3.81 + * libFLAC usually only requires the standard C library and C math
    3.82 + * library. In particular, threading is not used so there is no
    3.83 + * dependency on a thread library. However, libFLAC does not use
    3.84 + * global variables and should be thread-safe.
    3.85 + *
    3.86 + * libFLAC also supports encoding to and decoding from Ogg FLAC.
    3.87 + * However the metadata editing interfaces currently have limited
    3.88 + * read-only support for Ogg FLAC files.
    3.89 + *
    3.90 + * \section cpp_api FLAC C++ API
    3.91 + *
    3.92 + * The FLAC C++ API is a set of classes that encapsulate the
    3.93 + * structures and functions in libFLAC.  They provide slightly more
    3.94 + * functionality with respect to metadata but are otherwise
    3.95 + * equivalent.  For the most part, they share the same usage as
    3.96 + * their counterparts in libFLAC, and the FLAC C API documentation
    3.97 + * can be used as a supplement.  The public include files
    3.98 + * for the C++ API will be installed in your include area (for
    3.99 + * example /usr/include/FLAC++/...).
   3.100 + *
   3.101 + * libFLAC++ is also licensed under
   3.102 + * <A HREF="../license.html">Xiph's BSD license</A>.
   3.103 + *
   3.104 + * \section getting_started Getting Started
   3.105 + *
   3.106 + * A good starting point for learning the API is to browse through
   3.107 + * the <A HREF="modules.html">modules</A>.  Modules are logical
   3.108 + * groupings of related functions or classes, which correspond roughly
   3.109 + * to header files or sections of header files.  Each module includes a
   3.110 + * detailed description of the general usage of its functions or
   3.111 + * classes.
   3.112 + *
   3.113 + * From there you can go on to look at the documentation of
   3.114 + * individual functions.  You can see different views of the individual
   3.115 + * functions through the links in top bar across this page.
   3.116 + *
   3.117 + * If you prefer a more hands-on approach, you can jump right to some
   3.118 + * <A HREF="../documentation_example_code.html">example code</A>.
   3.119 + *
   3.120 + * \section porting_guide Porting Guide
   3.121 + *
   3.122 + * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
   3.123 + * has been introduced which gives detailed instructions on how to
   3.124 + * port your code to newer versions of FLAC.
   3.125 + *
   3.126 + * \section embedded_developers Embedded Developers
   3.127 + *
   3.128 + * libFLAC has grown larger over time as more functionality has been
   3.129 + * included, but much of it may be unnecessary for a particular embedded
   3.130 + * implementation.  Unused parts may be pruned by some simple editing of
   3.131 + * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
   3.132 + * metadata interface are all independent from each other.
   3.133 + *
   3.134 + * It is easiest to just describe the dependencies:
   3.135 + *
   3.136 + * - All modules depend on the \link flac_format Format \endlink module.
   3.137 + * - The decoders and encoders depend on the bitbuffer.
   3.138 + * - The decoder is independent of the encoder.  The encoder uses the
   3.139 + *   decoder because of the verify feature, but this can be removed if
   3.140 + *   not needed.
   3.141 + * - Parts of the metadata interface require the stream decoder (but not
   3.142 + *   the encoder).
   3.143 + * - Ogg support is selectable through the compile time macro
   3.144 + *   \c FLAC__HAS_OGG.
   3.145 + *
   3.146 + * For example, if your application only requires the stream decoder, no
   3.147 + * encoder, and no metadata interface, you can remove the stream encoder
   3.148 + * and the metadata interface, which will greatly reduce the size of the
   3.149 + * library.
   3.150 + *
   3.151 + * Also, there are several places in the libFLAC code with comments marked
   3.152 + * with "OPT:" where a #define can be changed to enable code that might be
   3.153 + * faster on a specific platform.  Experimenting with these can yield faster
   3.154 + * binaries.
   3.155 + */
   3.156 +
   3.157 +/** \defgroup porting Porting Guide for New Versions
   3.158 + *
   3.159 + * This module describes differences in the library interfaces from
   3.160 + * version to version.  It assists in the porting of code that uses
   3.161 + * the libraries to newer versions of FLAC.
   3.162 + *
   3.163 + * One simple facility for making porting easier that has been added
   3.164 + * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
   3.165 + * library's includes (e.g. \c include/FLAC/export.h).  The
   3.166 + * \c #defines mirror the libraries'
   3.167 + * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
   3.168 + * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
   3.169 + * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
   3.170 + * These can be used to support multiple versions of an API during the
   3.171 + * transition phase, e.g.
   3.172 + *
   3.173 + * \code
   3.174 + * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
   3.175 + *   legacy code
   3.176 + * #else
   3.177 + *   new code
   3.178 + * #endif
   3.179 + * \endcode
   3.180 + *
   3.181 + * The the source will work for multiple versions and the legacy code can
   3.182 + * easily be removed when the transition is complete.
   3.183 + *
   3.184 + * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
   3.185 + * include/FLAC/export.h), which can be used to determine whether or not
   3.186 + * the library has been compiled with support for Ogg FLAC.  This is
   3.187 + * simpler than trying to call an Ogg init function and catching the
   3.188 + * error.
   3.189 + */
   3.190 +
   3.191 +/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
   3.192 + *  \ingroup porting
   3.193 + *
   3.194 + *  \brief
   3.195 + *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
   3.196 + *
   3.197 + * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
   3.198 + * been simplified.  First, libOggFLAC has been merged into libFLAC and
   3.199 + * libOggFLAC++ has been merged into libFLAC++.  Second, both the three
   3.200 + * decoding layers and three encoding layers have been merged into a
   3.201 + * single stream decoder and stream encoder.  That is, the functionality
   3.202 + * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
   3.203 + * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
   3.204 + * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
   3.205 + * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  What this means
   3.206 + * is there is now a single API that can be used to encode or decode
   3.207 + * streams to/from native FLAC or Ogg FLAC and the single API can work
   3.208 + * on both seekable and non-seekable streams.
   3.209 + *
   3.210 + * Instead of creating an encoder or decoder of a certain layer, now the
   3.211 + * client will always create a FLAC__StreamEncoder or
   3.212 + * FLAC__StreamDecoder.  The old layers are now differentiated by the
   3.213 + * initialization function.  For example, for the decoder,
   3.214 + * FLAC__stream_decoder_init() has been replaced by
   3.215 + * FLAC__stream_decoder_init_stream().  This init function takes
   3.216 + * callbacks for the I/O, and the seeking callbacks are optional.  This
   3.217 + * allows the client to use the same object for seekable and
   3.218 + * non-seekable streams.  For decoding a FLAC file directly, the client
   3.219 + * can use FLAC__stream_decoder_init_file() and pass just a filename
   3.220 + * and fewer callbacks; most of the other callbacks are supplied
   3.221 + * internally.  For situations where fopen()ing by filename is not
   3.222 + * possible (e.g. Unicode filenames on Windows) the client can instead
   3.223 + * open the file itself and supply the FILE* to
   3.224 + * FLAC__stream_decoder_init_FILE().  The init functions now returns a
   3.225 + * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
   3.226 + * Since the callbacks and client data are now passed to the init
   3.227 + * function, the FLAC__stream_decoder_set_*_callback() functions and
   3.228 + * FLAC__stream_decoder_set_client_data() are no longer needed.  The
   3.229 + * rest of the calls to the decoder are the same as before.
   3.230 + *
   3.231 + * There are counterpart init functions for Ogg FLAC, e.g.
   3.232 + * FLAC__stream_decoder_init_ogg_stream().  All the rest of the calls
   3.233 + * and callbacks are the same as for native FLAC.
   3.234 + *
   3.235 + * As an example, in FLAC 1.1.2 a seekable stream decoder would have
   3.236 + * been set up like so:
   3.237 + *
   3.238 + * \code
   3.239 + * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
   3.240 + * if(decoder == NULL) do_something;
   3.241 + * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
   3.242 + * [... other settings ...]
   3.243 + * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
   3.244 + * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
   3.245 + * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
   3.246 + * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
   3.247 + * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
   3.248 + * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
   3.249 + * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
   3.250 + * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
   3.251 + * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
   3.252 + * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
   3.253 + * \endcode
   3.254 + *
   3.255 + * In FLAC 1.1.3 it is like this:
   3.256 + *
   3.257 + * \code
   3.258 + * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
   3.259 + * if(decoder == NULL) do_something;
   3.260 + * FLAC__stream_decoder_set_md5_checking(decoder, true);
   3.261 + * [... other settings ...]
   3.262 + * if(FLAC__stream_decoder_init_stream(
   3.263 + *   decoder,
   3.264 + *   my_read_callback,
   3.265 + *   my_seek_callback,      // or NULL
   3.266 + *   my_tell_callback,      // or NULL
   3.267 + *   my_length_callback,    // or NULL
   3.268 + *   my_eof_callback,       // or NULL
   3.269 + *   my_write_callback,
   3.270 + *   my_metadata_callback,  // or NULL
   3.271 + *   my_error_callback,
   3.272 + *   my_client_data
   3.273 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   3.274 + * \endcode
   3.275 + *
   3.276 + * or you could do;
   3.277 + *
   3.278 + * \code
   3.279 + * [...]
   3.280 + * FILE *file = fopen("somefile.flac","rb");
   3.281 + * if(file == NULL) do_somthing;
   3.282 + * if(FLAC__stream_decoder_init_FILE(
   3.283 + *   decoder,
   3.284 + *   file,
   3.285 + *   my_write_callback,
   3.286 + *   my_metadata_callback,  // or NULL
   3.287 + *   my_error_callback,
   3.288 + *   my_client_data
   3.289 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   3.290 + * \endcode
   3.291 + *
   3.292 + * or just:
   3.293 + *
   3.294 + * \code
   3.295 + * [...]
   3.296 + * if(FLAC__stream_decoder_init_file(
   3.297 + *   decoder,
   3.298 + *   "somefile.flac",
   3.299 + *   my_write_callback,
   3.300 + *   my_metadata_callback,  // or NULL
   3.301 + *   my_error_callback,
   3.302 + *   my_client_data
   3.303 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   3.304 + * \endcode
   3.305 + *
   3.306 + * Another small change to the decoder is in how it handles unparseable
   3.307 + * streams.  Before, when the decoder found an unparseable stream
   3.308 + * (reserved for when the decoder encounters a stream from a future
   3.309 + * encoder that it can't parse), it changed the state to
   3.310 + * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
   3.311 + * drops sync and calls the error callback with a new error code
   3.312 + * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
   3.313 + * more robust.  If your error callback does not discriminate on the the
   3.314 + * error state, your code does not need to be changed.
   3.315 + *
   3.316 + * The encoder now has a new setting:
   3.317 + * FLAC__stream_encoder_set_apodization().  This is for setting the
   3.318 + * method used to window the data before LPC analysis.  You only need to
   3.319 + * add a call to this function if the default is not suitable.   There
   3.320 + * are also two new convenience functions that may be useful:
   3.321 + * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
   3.322 + * FLAC__metadata_get_cuesheet().
   3.323 + *
   3.324 + * The \a bytes parameter to FLAC__StreamDecoderReadCallback,
   3.325 + * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
   3.326 + * is now \c size_t instead of \c unsigned.
   3.327 + */
   3.328 +
   3.329 +/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
   3.330 + *  \ingroup porting
   3.331 + *
   3.332 + *  \brief
   3.333 + *  This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
   3.334 + *
   3.335 + * There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
   3.336 + * There was a slight change in the implementation of
   3.337 + * FLAC__stream_encoder_set_metadata(); the function now makes a copy
   3.338 + * of the \a metadata array of pointers so the client no longer needs
   3.339 + * to maintain it after the call.  The objects themselves that are
   3.340 + * pointed to by the array are still not copied though and must be
   3.341 + * maintained until the call to FLAC__stream_encoder_finish().
   3.342 + */
   3.343 +
   3.344 +/** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0
   3.345 + *  \ingroup porting
   3.346 + *
   3.347 + *  \brief
   3.348 + *  This module describes porting from FLAC 1.1.4 to FLAC 1.2.0.
   3.349 + *
   3.350 + * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0.
   3.351 + * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added.
   3.352 + * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added.
   3.353 + *
   3.354 + * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN
   3.355 + * has changed to reflect the conversion of one of the reserved bits
   3.356 + * into active use.  It used to be \c 2 and now is \c 1.  However the
   3.357 + * FLAC frame header length has not changed, so to skip the proper
   3.358 + * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN +
   3.359 + * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN
   3.360 + */
   3.361 +
   3.362 +/** \defgroup flac FLAC C API
   3.363 + *
   3.364 + * The FLAC C API is the interface to libFLAC, a set of structures
   3.365 + * describing the components of FLAC streams, and functions for
   3.366 + * encoding and decoding streams, as well as manipulating FLAC
   3.367 + * metadata in files.
   3.368 + *
   3.369 + * You should start with the format components as all other modules
   3.370 + * are dependent on it.
   3.371 + */
   3.372 +
   3.373 +#endif
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/VisualC/external/include/FLAC/assert.h	Mon Jan 09 04:20:54 2012 -0500
     4.3 @@ -0,0 +1,45 @@
     4.4 +/* libFLAC - Free Lossless Audio Codec library
     4.5 + * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     4.6 + *
     4.7 + * Redistribution and use in source and binary forms, with or without
     4.8 + * modification, are permitted provided that the following conditions
     4.9 + * are met:
    4.10 + *
    4.11 + * - Redistributions of source code must retain the above copyright
    4.12 + * notice, this list of conditions and the following disclaimer.
    4.13 + *
    4.14 + * - Redistributions in binary form must reproduce the above copyright
    4.15 + * notice, this list of conditions and the following disclaimer in the
    4.16 + * documentation and/or other materials provided with the distribution.
    4.17 + *
    4.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    4.19 + * contributors may be used to endorse or promote products derived from
    4.20 + * this software without specific prior written permission.
    4.21 + *
    4.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    4.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    4.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    4.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    4.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    4.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    4.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    4.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    4.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    4.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    4.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    4.33 + */
    4.34 +
    4.35 +#ifndef FLAC__ASSERT_H
    4.36 +#define FLAC__ASSERT_H
    4.37 +
    4.38 +/* we need this since some compilers (like MSVC) leave assert()s on release code (and we don't want to use their ASSERT) */
    4.39 +#ifdef DEBUG
    4.40 +#include <assert.h>
    4.41 +#define FLAC__ASSERT(x) assert(x)
    4.42 +#define FLAC__ASSERT_DECLARATION(x) x
    4.43 +#else
    4.44 +#define FLAC__ASSERT(x)
    4.45 +#define FLAC__ASSERT_DECLARATION(x)
    4.46 +#endif
    4.47 +
    4.48 +#endif
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/VisualC/external/include/FLAC/callback.h	Mon Jan 09 04:20:54 2012 -0500
     5.3 @@ -0,0 +1,184 @@
     5.4 +/* libFLAC - Free Lossless Audio Codec library
     5.5 + * Copyright (C) 2004,2005,2006,2007  Josh Coalson
     5.6 + *
     5.7 + * Redistribution and use in source and binary forms, with or without
     5.8 + * modification, are permitted provided that the following conditions
     5.9 + * are met:
    5.10 + *
    5.11 + * - Redistributions of source code must retain the above copyright
    5.12 + * notice, this list of conditions and the following disclaimer.
    5.13 + *
    5.14 + * - Redistributions in binary form must reproduce the above copyright
    5.15 + * notice, this list of conditions and the following disclaimer in the
    5.16 + * documentation and/or other materials provided with the distribution.
    5.17 + *
    5.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    5.19 + * contributors may be used to endorse or promote products derived from
    5.20 + * this software without specific prior written permission.
    5.21 + *
    5.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    5.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    5.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    5.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    5.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    5.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    5.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    5.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    5.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    5.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    5.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    5.33 + */
    5.34 +
    5.35 +#ifndef FLAC__CALLBACK_H
    5.36 +#define FLAC__CALLBACK_H
    5.37 +
    5.38 +#include "ordinals.h"
    5.39 +#include <stdlib.h> /* for size_t */
    5.40 +
    5.41 +/** \file include/FLAC/callback.h
    5.42 + *
    5.43 + *  \brief
    5.44 + *  This module defines the structures for describing I/O callbacks
    5.45 + *  to the other FLAC interfaces.
    5.46 + *
    5.47 + *  See the detailed documentation for callbacks in the
    5.48 + *  \link flac_callbacks callbacks \endlink module.
    5.49 + */
    5.50 +
    5.51 +/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
    5.52 + *  \ingroup flac
    5.53 + *
    5.54 + *  \brief
    5.55 + *  This module defines the structures for describing I/O callbacks
    5.56 + *  to the other FLAC interfaces.
    5.57 + *
    5.58 + *  The purpose of the I/O callback functions is to create a common way
    5.59 + *  for the metadata interfaces to handle I/O.
    5.60 + *
    5.61 + *  Originally the metadata interfaces required filenames as the way of
    5.62 + *  specifying FLAC files to operate on.  This is problematic in some
    5.63 + *  environments so there is an additional option to specify a set of
    5.64 + *  callbacks for doing I/O on the FLAC file, instead of the filename.
    5.65 + *
    5.66 + *  In addition to the callbacks, a FLAC__IOHandle type is defined as an
    5.67 + *  opaque structure for a data source.
    5.68 + *
    5.69 + *  The callback function prototypes are similar (but not identical) to the
    5.70 + *  stdio functions fread, fwrite, fseek, ftell, feof, and fclose.  If you use
    5.71 + *  stdio streams to implement the callbacks, you can pass fread, fwrite, and
    5.72 + *  fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
    5.73 + *  FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
    5.74 + *  is required.  \warning You generally CANNOT directly use fseek or ftell
    5.75 + *  for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
    5.76 + *  these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
    5.77 + *  large files.  You will have to find an equivalent function (e.g. ftello),
    5.78 + *  or write a wrapper.  The same is true for feof() since this is usually
    5.79 + *  implemented as a macro, not as a function whose address can be taken.
    5.80 + *
    5.81 + * \{
    5.82 + */
    5.83 +
    5.84 +#ifdef __cplusplus
    5.85 +extern "C" {
    5.86 +#endif
    5.87 +
    5.88 +/** This is the opaque handle type used by the callbacks.  Typically
    5.89 + *  this is a \c FILE* or address of a file descriptor.
    5.90 + */
    5.91 +typedef void* FLAC__IOHandle;
    5.92 +
    5.93 +/** Signature for the read callback.
    5.94 + *  The signature and semantics match POSIX fread() implementations
    5.95 + *  and can generally be used interchangeably.
    5.96 + *
    5.97 + * \param  ptr      The address of the read buffer.
    5.98 + * \param  size     The size of the records to be read.
    5.99 + * \param  nmemb    The number of records to be read.
   5.100 + * \param  handle   The handle to the data source.
   5.101 + * \retval size_t
   5.102 + *    The number of records read.
   5.103 + */
   5.104 +typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   5.105 +
   5.106 +/** Signature for the write callback.
   5.107 + *  The signature and semantics match POSIX fwrite() implementations
   5.108 + *  and can generally be used interchangeably.
   5.109 + *
   5.110 + * \param  ptr      The address of the write buffer.
   5.111 + * \param  size     The size of the records to be written.
   5.112 + * \param  nmemb    The number of records to be written.
   5.113 + * \param  handle   The handle to the data source.
   5.114 + * \retval size_t
   5.115 + *    The number of records written.
   5.116 + */
   5.117 +typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   5.118 +
   5.119 +/** Signature for the seek callback.
   5.120 + *  The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
   5.121 + *  EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
   5.122 + *  and 32-bits wide.
   5.123 + *
   5.124 + * \param  handle   The handle to the data source.
   5.125 + * \param  offset   The new position, relative to \a whence
   5.126 + * \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
   5.127 + * \retval int
   5.128 + *    \c 0 on success, \c -1 on error.
   5.129 + */
   5.130 +typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
   5.131 +
   5.132 +/** Signature for the tell callback.
   5.133 + *  The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
   5.134 + *  EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
   5.135 + *  and 32-bits wide.
   5.136 + *
   5.137 + * \param  handle   The handle to the data source.
   5.138 + * \retval FLAC__int64
   5.139 + *    The current position on success, \c -1 on error.
   5.140 + */
   5.141 +typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
   5.142 +
   5.143 +/** Signature for the EOF callback.
   5.144 + *  The signature and semantics mostly match POSIX feof() but WATCHOUT:
   5.145 + *  on many systems, feof() is a macro, so in this case a wrapper function
   5.146 + *  must be provided instead.
   5.147 + *
   5.148 + * \param  handle   The handle to the data source.
   5.149 + * \retval int
   5.150 + *    \c 0 if not at end of file, nonzero if at end of file.
   5.151 + */
   5.152 +typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
   5.153 +
   5.154 +/** Signature for the close callback.
   5.155 + *  The signature and semantics match POSIX fclose() implementations
   5.156 + *  and can generally be used interchangeably.
   5.157 + *
   5.158 + * \param  handle   The handle to the data source.
   5.159 + * \retval int
   5.160 + *    \c 0 on success, \c EOF on error.
   5.161 + */
   5.162 +typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
   5.163 +
   5.164 +/** A structure for holding a set of callbacks.
   5.165 + *  Each FLAC interface that requires a FLAC__IOCallbacks structure will
   5.166 + *  describe which of the callbacks are required.  The ones that are not
   5.167 + *  required may be set to NULL.
   5.168 + *
   5.169 + *  If the seek requirement for an interface is optional, you can signify that
   5.170 + *  a data sorce is not seekable by setting the \a seek field to \c NULL.
   5.171 + */
   5.172 +typedef struct {
   5.173 +	FLAC__IOCallback_Read read;
   5.174 +	FLAC__IOCallback_Write write;
   5.175 +	FLAC__IOCallback_Seek seek;
   5.176 +	FLAC__IOCallback_Tell tell;
   5.177 +	FLAC__IOCallback_Eof eof;
   5.178 +	FLAC__IOCallback_Close close;
   5.179 +} FLAC__IOCallbacks;
   5.180 +
   5.181 +/* \} */
   5.182 +
   5.183 +#ifdef __cplusplus
   5.184 +}
   5.185 +#endif
   5.186 +
   5.187 +#endif
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/VisualC/external/include/FLAC/export.h	Mon Jan 09 04:20:54 2012 -0500
     6.3 @@ -0,0 +1,91 @@
     6.4 +/* libFLAC - Free Lossless Audio Codec library
     6.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     6.6 + *
     6.7 + * Redistribution and use in source and binary forms, with or without
     6.8 + * modification, are permitted provided that the following conditions
     6.9 + * are met:
    6.10 + *
    6.11 + * - Redistributions of source code must retain the above copyright
    6.12 + * notice, this list of conditions and the following disclaimer.
    6.13 + *
    6.14 + * - Redistributions in binary form must reproduce the above copyright
    6.15 + * notice, this list of conditions and the following disclaimer in the
    6.16 + * documentation and/or other materials provided with the distribution.
    6.17 + *
    6.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    6.19 + * contributors may be used to endorse or promote products derived from
    6.20 + * this software without specific prior written permission.
    6.21 + *
    6.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    6.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    6.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    6.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    6.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    6.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    6.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    6.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    6.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    6.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    6.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    6.33 + */
    6.34 +
    6.35 +#ifndef FLAC__EXPORT_H
    6.36 +#define FLAC__EXPORT_H
    6.37 +
    6.38 +/** \file include/FLAC/export.h
    6.39 + *
    6.40 + *  \brief
    6.41 + *  This module contains #defines and symbols for exporting function
    6.42 + *  calls, and providing version information and compiled-in features.
    6.43 + *
    6.44 + *  See the \link flac_export export \endlink module.
    6.45 + */
    6.46 +
    6.47 +/** \defgroup flac_export FLAC/export.h: export symbols
    6.48 + *  \ingroup flac
    6.49 + *
    6.50 + *  \brief
    6.51 + *  This module contains #defines and symbols for exporting function
    6.52 + *  calls, and providing version information and compiled-in features.
    6.53 + *
    6.54 + *  If you are compiling with MSVC and will link to the static library
    6.55 + *  (libFLAC.lib) you should define FLAC__NO_DLL in your project to
    6.56 + *  make sure the symbols are exported properly.
    6.57 + *
    6.58 + * \{
    6.59 + */
    6.60 +
    6.61 +#if defined(FLAC__NO_DLL) || !defined(_MSC_VER)
    6.62 +#define FLAC_API
    6.63 +
    6.64 +#else
    6.65 +
    6.66 +#ifdef FLAC_API_EXPORTS
    6.67 +#define	FLAC_API	_declspec(dllexport)
    6.68 +#else
    6.69 +#define FLAC_API	_declspec(dllimport)
    6.70 +
    6.71 +#endif
    6.72 +#endif
    6.73 +
    6.74 +/** These #defines will mirror the libtool-based library version number, see
    6.75 + * http://www.gnu.org/software/libtool/manual.html#Libtool-versioning
    6.76 + */
    6.77 +#define FLAC_API_VERSION_CURRENT 10
    6.78 +#define FLAC_API_VERSION_REVISION 0 /**< see above */
    6.79 +#define FLAC_API_VERSION_AGE 2 /**< see above */
    6.80 +
    6.81 +#ifdef __cplusplus
    6.82 +extern "C" {
    6.83 +#endif
    6.84 +
    6.85 +/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */
    6.86 +extern FLAC_API int FLAC_API_SUPPORTS_OGG_FLAC;
    6.87 +
    6.88 +#ifdef __cplusplus
    6.89 +}
    6.90 +#endif
    6.91 +
    6.92 +/* \} */
    6.93 +
    6.94 +#endif
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/VisualC/external/include/FLAC/format.h	Mon Jan 09 04:20:54 2012 -0500
     7.3 @@ -0,0 +1,1010 @@
     7.4 +/* libFLAC - Free Lossless Audio Codec library
     7.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     7.6 + *
     7.7 + * Redistribution and use in source and binary forms, with or without
     7.8 + * modification, are permitted provided that the following conditions
     7.9 + * are met:
    7.10 + *
    7.11 + * - Redistributions of source code must retain the above copyright
    7.12 + * notice, this list of conditions and the following disclaimer.
    7.13 + *
    7.14 + * - Redistributions in binary form must reproduce the above copyright
    7.15 + * notice, this list of conditions and the following disclaimer in the
    7.16 + * documentation and/or other materials provided with the distribution.
    7.17 + *
    7.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    7.19 + * contributors may be used to endorse or promote products derived from
    7.20 + * this software without specific prior written permission.
    7.21 + *
    7.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    7.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    7.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    7.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    7.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    7.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    7.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    7.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    7.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    7.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    7.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    7.33 + */
    7.34 +
    7.35 +#ifndef FLAC__FORMAT_H
    7.36 +#define FLAC__FORMAT_H
    7.37 +
    7.38 +#include "export.h"
    7.39 +#include "ordinals.h"
    7.40 +
    7.41 +#ifdef __cplusplus
    7.42 +extern "C" {
    7.43 +#endif
    7.44 +
    7.45 +/** \file include/FLAC/format.h
    7.46 + *
    7.47 + *  \brief
    7.48 + *  This module contains structure definitions for the representation
    7.49 + *  of FLAC format components in memory.  These are the basic
    7.50 + *  structures used by the rest of the interfaces.
    7.51 + *
    7.52 + *  See the detailed documentation in the
    7.53 + *  \link flac_format format \endlink module.
    7.54 + */
    7.55 +
    7.56 +/** \defgroup flac_format FLAC/format.h: format components
    7.57 + *  \ingroup flac
    7.58 + *
    7.59 + *  \brief
    7.60 + *  This module contains structure definitions for the representation
    7.61 + *  of FLAC format components in memory.  These are the basic
    7.62 + *  structures used by the rest of the interfaces.
    7.63 + *
    7.64 + *  First, you should be familiar with the
    7.65 + *  <A HREF="../format.html">FLAC format</A>.  Many of the values here
    7.66 + *  follow directly from the specification.  As a user of libFLAC, the
    7.67 + *  interesting parts really are the structures that describe the frame
    7.68 + *  header and metadata blocks.
    7.69 + *
    7.70 + *  The format structures here are very primitive, designed to store
    7.71 + *  information in an efficient way.  Reading information from the
    7.72 + *  structures is easy but creating or modifying them directly is
    7.73 + *  more complex.  For the most part, as a user of a library, editing
    7.74 + *  is not necessary; however, for metadata blocks it is, so there are
    7.75 + *  convenience functions provided in the \link flac_metadata metadata
    7.76 + *  module \endlink to simplify the manipulation of metadata blocks.
    7.77 + *
    7.78 + * \note
    7.79 + * It's not the best convention, but symbols ending in _LEN are in bits
    7.80 + * and _LENGTH are in bytes.  _LENGTH symbols are \#defines instead of
    7.81 + * global variables because they are usually used when declaring byte
    7.82 + * arrays and some compilers require compile-time knowledge of array
    7.83 + * sizes when declared on the stack.
    7.84 + *
    7.85 + * \{
    7.86 + */
    7.87 +
    7.88 +
    7.89 +/*
    7.90 +	Most of the values described in this file are defined by the FLAC
    7.91 +	format specification.  There is nothing to tune here.
    7.92 +*/
    7.93 +
    7.94 +/** The largest legal metadata type code. */
    7.95 +#define FLAC__MAX_METADATA_TYPE_CODE (126u)
    7.96 +
    7.97 +/** The minimum block size, in samples, permitted by the format. */
    7.98 +#define FLAC__MIN_BLOCK_SIZE (16u)
    7.99 +
   7.100 +/** The maximum block size, in samples, permitted by the format. */
   7.101 +#define FLAC__MAX_BLOCK_SIZE (65535u)
   7.102 +
   7.103 +/** The maximum block size, in samples, permitted by the FLAC subset for
   7.104 + *  sample rates up to 48kHz. */
   7.105 +#define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u)
   7.106 +
   7.107 +/** The maximum number of channels permitted by the format. */
   7.108 +#define FLAC__MAX_CHANNELS (8u)
   7.109 +
   7.110 +/** The minimum sample resolution permitted by the format. */
   7.111 +#define FLAC__MIN_BITS_PER_SAMPLE (4u)
   7.112 +
   7.113 +/** The maximum sample resolution permitted by the format. */
   7.114 +#define FLAC__MAX_BITS_PER_SAMPLE (32u)
   7.115 +
   7.116 +/** The maximum sample resolution permitted by libFLAC.
   7.117 + *
   7.118 + * \warning
   7.119 + * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format.  However,
   7.120 + * the reference encoder/decoder is currently limited to 24 bits because
   7.121 + * of prevalent 32-bit math, so make sure and use this value when
   7.122 + * appropriate.
   7.123 + */
   7.124 +#define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
   7.125 +
   7.126 +/** The maximum sample rate permitted by the format.  The value is
   7.127 + *  ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A>
   7.128 + *  as to why.
   7.129 + */
   7.130 +#define FLAC__MAX_SAMPLE_RATE (655350u)
   7.131 +
   7.132 +/** The maximum LPC order permitted by the format. */
   7.133 +#define FLAC__MAX_LPC_ORDER (32u)
   7.134 +
   7.135 +/** The maximum LPC order permitted by the FLAC subset for sample rates
   7.136 + *  up to 48kHz. */
   7.137 +#define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u)
   7.138 +
   7.139 +/** The minimum quantized linear predictor coefficient precision
   7.140 + *  permitted by the format.
   7.141 + */
   7.142 +#define FLAC__MIN_QLP_COEFF_PRECISION (5u)
   7.143 +
   7.144 +/** The maximum quantized linear predictor coefficient precision
   7.145 + *  permitted by the format.
   7.146 + */
   7.147 +#define FLAC__MAX_QLP_COEFF_PRECISION (15u)
   7.148 +
   7.149 +/** The maximum order of the fixed predictors permitted by the format. */
   7.150 +#define FLAC__MAX_FIXED_ORDER (4u)
   7.151 +
   7.152 +/** The maximum Rice partition order permitted by the format. */
   7.153 +#define FLAC__MAX_RICE_PARTITION_ORDER (15u)
   7.154 +
   7.155 +/** The maximum Rice partition order permitted by the FLAC Subset. */
   7.156 +#define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
   7.157 +
   7.158 +/** The version string of the release, stamped onto the libraries and binaries.
   7.159 + *
   7.160 + * \note
   7.161 + * This does not correspond to the shared library version number, which
   7.162 + * is used to determine binary compatibility.
   7.163 + */
   7.164 +extern FLAC_API const char *FLAC__VERSION_STRING;
   7.165 +
   7.166 +/** The vendor string inserted by the encoder into the VORBIS_COMMENT block.
   7.167 + *  This is a NUL-terminated ASCII string; when inserted into the
   7.168 + *  VORBIS_COMMENT the trailing null is stripped.
   7.169 + */
   7.170 +extern FLAC_API const char *FLAC__VENDOR_STRING;
   7.171 +
   7.172 +/** The byte string representation of the beginning of a FLAC stream. */
   7.173 +extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
   7.174 +
   7.175 +/** The 32-bit integer big-endian representation of the beginning of
   7.176 + *  a FLAC stream.
   7.177 + */
   7.178 +extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
   7.179 +
   7.180 +/** The length of the FLAC signature in bits. */
   7.181 +extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
   7.182 +
   7.183 +/** The length of the FLAC signature in bytes. */
   7.184 +#define FLAC__STREAM_SYNC_LENGTH (4u)
   7.185 +
   7.186 +
   7.187 +/*****************************************************************************
   7.188 + *
   7.189 + * Subframe structures
   7.190 + *
   7.191 + *****************************************************************************/
   7.192 +
   7.193 +/*****************************************************************************/
   7.194 +
   7.195 +/** An enumeration of the available entropy coding methods. */
   7.196 +typedef enum {
   7.197 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0,
   7.198 +	/**< Residual is coded by partitioning into contexts, each with it's own
   7.199 +	 * 4-bit Rice parameter. */
   7.200 +
   7.201 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2 = 1
   7.202 +	/**< Residual is coded by partitioning into contexts, each with it's own
   7.203 +	 * 5-bit Rice parameter. */
   7.204 +} FLAC__EntropyCodingMethodType;
   7.205 +
   7.206 +/** Maps a FLAC__EntropyCodingMethodType to a C string.
   7.207 + *
   7.208 + *  Using a FLAC__EntropyCodingMethodType as the index to this array will
   7.209 + *  give the string equivalent.  The contents should not be modified.
   7.210 + */
   7.211 +extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
   7.212 +
   7.213 +
   7.214 +/** Contents of a Rice partitioned residual
   7.215 + */
   7.216 +typedef struct {
   7.217 +
   7.218 +	unsigned *parameters;
   7.219 +	/**< The Rice parameters for each context. */
   7.220 +
   7.221 +	unsigned *raw_bits;
   7.222 +	/**< Widths for escape-coded partitions.  Will be non-zero for escaped
   7.223 +	 * partitions and zero for unescaped partitions.
   7.224 +	 */
   7.225 +
   7.226 +	unsigned capacity_by_order;
   7.227 +	/**< The capacity of the \a parameters and \a raw_bits arrays
   7.228 +	 * specified as an order, i.e. the number of array elements
   7.229 +	 * allocated is 2 ^ \a capacity_by_order.
   7.230 +	 */
   7.231 +} FLAC__EntropyCodingMethod_PartitionedRiceContents;
   7.232 +
   7.233 +/** Header for a Rice partitioned residual.  (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>)
   7.234 + */
   7.235 +typedef struct {
   7.236 +
   7.237 +	unsigned order;
   7.238 +	/**< The partition order, i.e. # of contexts = 2 ^ \a order. */
   7.239 +
   7.240 +	const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
   7.241 +	/**< The context's Rice parameters and/or raw bits. */
   7.242 +
   7.243 +} FLAC__EntropyCodingMethod_PartitionedRice;
   7.244 +
   7.245 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */
   7.246 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */
   7.247 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN; /**< == 5 (bits) */
   7.248 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */
   7.249 +
   7.250 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
   7.251 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
   7.252 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_ESCAPE_PARAMETER;
   7.253 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN)-1 */
   7.254 +
   7.255 +/** Header for the entropy coding method.  (c.f. <A HREF="../format.html#residual">format specification</A>)
   7.256 + */
   7.257 +typedef struct {
   7.258 +	FLAC__EntropyCodingMethodType type;
   7.259 +	union {
   7.260 +		FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
   7.261 +	} data;
   7.262 +} FLAC__EntropyCodingMethod;
   7.263 +
   7.264 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */
   7.265 +
   7.266 +/*****************************************************************************/
   7.267 +
   7.268 +/** An enumeration of the available subframe types. */
   7.269 +typedef enum {
   7.270 +	FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */
   7.271 +	FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */
   7.272 +	FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */
   7.273 +	FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */
   7.274 +} FLAC__SubframeType;
   7.275 +
   7.276 +/** Maps a FLAC__SubframeType to a C string.
   7.277 + *
   7.278 + *  Using a FLAC__SubframeType as the index to this array will
   7.279 + *  give the string equivalent.  The contents should not be modified.
   7.280 + */
   7.281 +extern FLAC_API const char * const FLAC__SubframeTypeString[];
   7.282 +
   7.283 +
   7.284 +/** CONSTANT subframe.  (c.f. <A HREF="../format.html#subframe_constant">format specification</A>)
   7.285 + */
   7.286 +typedef struct {
   7.287 +	FLAC__int32 value; /**< The constant signal value. */
   7.288 +} FLAC__Subframe_Constant;
   7.289 +
   7.290 +
   7.291 +/** VERBATIM subframe.  (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>)
   7.292 + */
   7.293 +typedef struct {
   7.294 +	const FLAC__int32 *data; /**< A pointer to verbatim signal. */
   7.295 +} FLAC__Subframe_Verbatim;
   7.296 +
   7.297 +
   7.298 +/** FIXED subframe.  (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>)
   7.299 + */
   7.300 +typedef struct {
   7.301 +	FLAC__EntropyCodingMethod entropy_coding_method;
   7.302 +	/**< The residual coding method. */
   7.303 +
   7.304 +	unsigned order;
   7.305 +	/**< The polynomial order. */
   7.306 +
   7.307 +	FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
   7.308 +	/**< Warmup samples to prime the predictor, length == order. */
   7.309 +
   7.310 +	const FLAC__int32 *residual;
   7.311 +	/**< The residual signal, length == (blocksize minus order) samples. */
   7.312 +} FLAC__Subframe_Fixed;
   7.313 +
   7.314 +
   7.315 +/** LPC subframe.  (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>)
   7.316 + */
   7.317 +typedef struct {
   7.318 +	FLAC__EntropyCodingMethod entropy_coding_method;
   7.319 +	/**< The residual coding method. */
   7.320 +
   7.321 +	unsigned order;
   7.322 +	/**< The FIR order. */
   7.323 +
   7.324 +	unsigned qlp_coeff_precision;
   7.325 +	/**< Quantized FIR filter coefficient precision in bits. */
   7.326 +
   7.327 +	int quantization_level;
   7.328 +	/**< The qlp coeff shift needed. */
   7.329 +
   7.330 +	FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
   7.331 +	/**< FIR filter coefficients. */
   7.332 +
   7.333 +	FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
   7.334 +	/**< Warmup samples to prime the predictor, length == order. */
   7.335 +
   7.336 +	const FLAC__int32 *residual;
   7.337 +	/**< The residual signal, length == (blocksize minus order) samples. */
   7.338 +} FLAC__Subframe_LPC;
   7.339 +
   7.340 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */
   7.341 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */
   7.342 +
   7.343 +
   7.344 +/** FLAC subframe structure.  (c.f. <A HREF="../format.html#subframe">format specification</A>)
   7.345 + */
   7.346 +typedef struct {
   7.347 +	FLAC__SubframeType type;
   7.348 +	union {
   7.349 +		FLAC__Subframe_Constant constant;
   7.350 +		FLAC__Subframe_Fixed fixed;
   7.351 +		FLAC__Subframe_LPC lpc;
   7.352 +		FLAC__Subframe_Verbatim verbatim;
   7.353 +	} data;
   7.354 +	unsigned wasted_bits;
   7.355 +} FLAC__Subframe;
   7.356 +
   7.357 +/** == 1 (bit)
   7.358 + *
   7.359 + * This used to be a zero-padding bit (hence the name
   7.360 + * FLAC__SUBFRAME_ZERO_PAD_LEN) but is now a reserved bit.  It still has a
   7.361 + * mandatory value of \c 0 but in the future may take on the value \c 0 or \c 1
   7.362 + * to mean something else.
   7.363 + */
   7.364 +extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN;
   7.365 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */
   7.366 +extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */
   7.367 +
   7.368 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */
   7.369 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */
   7.370 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */
   7.371 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */
   7.372 +
   7.373 +/*****************************************************************************/
   7.374 +
   7.375 +
   7.376 +/*****************************************************************************
   7.377 + *
   7.378 + * Frame structures
   7.379 + *
   7.380 + *****************************************************************************/
   7.381 +
   7.382 +/** An enumeration of the available channel assignments. */
   7.383 +typedef enum {
   7.384 +	FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */
   7.385 +	FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */
   7.386 +	FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */
   7.387 +	FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */
   7.388 +} FLAC__ChannelAssignment;
   7.389 +
   7.390 +/** Maps a FLAC__ChannelAssignment to a C string.
   7.391 + *
   7.392 + *  Using a FLAC__ChannelAssignment as the index to this array will
   7.393 + *  give the string equivalent.  The contents should not be modified.
   7.394 + */
   7.395 +extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
   7.396 +
   7.397 +/** An enumeration of the possible frame numbering methods. */
   7.398 +typedef enum {
   7.399 +	FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */
   7.400 +	FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */
   7.401 +} FLAC__FrameNumberType;
   7.402 +
   7.403 +/** Maps a FLAC__FrameNumberType to a C string.
   7.404 + *
   7.405 + *  Using a FLAC__FrameNumberType as the index to this array will
   7.406 + *  give the string equivalent.  The contents should not be modified.
   7.407 + */
   7.408 +extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
   7.409 +
   7.410 +
   7.411 +/** FLAC frame header structure.  (c.f. <A HREF="../format.html#frame_header">format specification</A>)
   7.412 + */
   7.413 +typedef struct {
   7.414 +	unsigned blocksize;
   7.415 +	/**< The number of samples per subframe. */
   7.416 +
   7.417 +	unsigned sample_rate;
   7.418 +	/**< The sample rate in Hz. */
   7.419 +
   7.420 +	unsigned channels;
   7.421 +	/**< The number of channels (== number of subframes). */
   7.422 +
   7.423 +	FLAC__ChannelAssignment channel_assignment;
   7.424 +	/**< The channel assignment for the frame. */
   7.425 +
   7.426 +	unsigned bits_per_sample;
   7.427 +	/**< The sample resolution. */
   7.428 +
   7.429 +	FLAC__FrameNumberType number_type;
   7.430 +	/**< The numbering scheme used for the frame.  As a convenience, the
   7.431 +	 * decoder will always convert a frame number to a sample number because
   7.432 +	 * the rules are complex. */
   7.433 +
   7.434 +	union {
   7.435 +		FLAC__uint32 frame_number;
   7.436 +		FLAC__uint64 sample_number;
   7.437 +	} number;
   7.438 +	/**< The frame number or sample number of first sample in frame;
   7.439 +	 * use the \a number_type value to determine which to use. */
   7.440 +
   7.441 +	FLAC__uint8 crc;
   7.442 +	/**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0)
   7.443 +	 * of the raw frame header bytes, meaning everything before the CRC byte
   7.444 +	 * including the sync code.
   7.445 +	 */
   7.446 +} FLAC__FrameHeader;
   7.447 +
   7.448 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */
   7.449 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */
   7.450 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 1 (bits) */
   7.451 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN; /**< == 1 (bits) */
   7.452 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */
   7.453 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */
   7.454 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */
   7.455 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */
   7.456 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */
   7.457 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */
   7.458 +
   7.459 +
   7.460 +/** FLAC frame footer structure.  (c.f. <A HREF="../format.html#frame_footer">format specification</A>)
   7.461 + */
   7.462 +typedef struct {
   7.463 +	FLAC__uint16 crc;
   7.464 +	/**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with
   7.465 +	 * 0) of the bytes before the crc, back to and including the frame header
   7.466 +	 * sync code.
   7.467 +	 */
   7.468 +} FLAC__FrameFooter;
   7.469 +
   7.470 +extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */
   7.471 +
   7.472 +
   7.473 +/** FLAC frame structure.  (c.f. <A HREF="../format.html#frame">format specification</A>)
   7.474 + */
   7.475 +typedef struct {
   7.476 +	FLAC__FrameHeader header;
   7.477 +	FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
   7.478 +	FLAC__FrameFooter footer;
   7.479 +} FLAC__Frame;
   7.480 +
   7.481 +/*****************************************************************************/
   7.482 +
   7.483 +
   7.484 +/*****************************************************************************
   7.485 + *
   7.486 + * Meta-data structures
   7.487 + *
   7.488 + *****************************************************************************/
   7.489 +
   7.490 +/** An enumeration of the available metadata block types. */
   7.491 +typedef enum {
   7.492 +
   7.493 +	FLAC__METADATA_TYPE_STREAMINFO = 0,
   7.494 +	/**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */
   7.495 +
   7.496 +	FLAC__METADATA_TYPE_PADDING = 1,
   7.497 +	/**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */
   7.498 +
   7.499 +	FLAC__METADATA_TYPE_APPLICATION = 2,
   7.500 +	/**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */
   7.501 +
   7.502 +	FLAC__METADATA_TYPE_SEEKTABLE = 3,
   7.503 +	/**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
   7.504 +
   7.505 +	FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
   7.506 +	/**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */
   7.507 +
   7.508 +	FLAC__METADATA_TYPE_CUESHEET = 5,
   7.509 +	/**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
   7.510 +
   7.511 +	FLAC__METADATA_TYPE_PICTURE = 6,
   7.512 +	/**< <A HREF="../format.html#metadata_block_picture">PICTURE</A> block */
   7.513 +
   7.514 +	FLAC__METADATA_TYPE_UNDEFINED = 7
   7.515 +	/**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
   7.516 +
   7.517 +} FLAC__MetadataType;
   7.518 +
   7.519 +/** Maps a FLAC__MetadataType to a C string.
   7.520 + *
   7.521 + *  Using a FLAC__MetadataType as the index to this array will
   7.522 + *  give the string equivalent.  The contents should not be modified.
   7.523 + */
   7.524 +extern FLAC_API const char * const FLAC__MetadataTypeString[];
   7.525 +
   7.526 +
   7.527 +/** FLAC STREAMINFO structure.  (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>)
   7.528 + */
   7.529 +typedef struct {
   7.530 +	unsigned min_blocksize, max_blocksize;
   7.531 +	unsigned min_framesize, max_framesize;
   7.532 +	unsigned sample_rate;
   7.533 +	unsigned channels;
   7.534 +	unsigned bits_per_sample;
   7.535 +	FLAC__uint64 total_samples;
   7.536 +	FLAC__byte md5sum[16];
   7.537 +} FLAC__StreamMetadata_StreamInfo;
   7.538 +
   7.539 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */
   7.540 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */
   7.541 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */
   7.542 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */
   7.543 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */
   7.544 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */
   7.545 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */
   7.546 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */
   7.547 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */
   7.548 +
   7.549 +/** The total stream length of the STREAMINFO block in bytes. */
   7.550 +#define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
   7.551 +
   7.552 +/** FLAC PADDING structure.  (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>)
   7.553 + */
   7.554 +typedef struct {
   7.555 +	int dummy;
   7.556 +	/**< Conceptually this is an empty struct since we don't store the
   7.557 +	 * padding bytes.  Empty structs are not allowed by some C compilers,
   7.558 +	 * hence the dummy.
   7.559 +	 */
   7.560 +} FLAC__StreamMetadata_Padding;
   7.561 +
   7.562 +
   7.563 +/** FLAC APPLICATION structure.  (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>)
   7.564 + */
   7.565 +typedef struct {
   7.566 +	FLAC__byte id[4];
   7.567 +	FLAC__byte *data;
   7.568 +} FLAC__StreamMetadata_Application;
   7.569 +
   7.570 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */
   7.571 +
   7.572 +/** SeekPoint structure used in SEEKTABLE blocks.  (c.f. <A HREF="../format.html#seekpoint">format specification</A>)
   7.573 + */
   7.574 +typedef struct {
   7.575 +	FLAC__uint64 sample_number;
   7.576 +	/**<  The sample number of the target frame. */
   7.577 +
   7.578 +	FLAC__uint64 stream_offset;
   7.579 +	/**< The offset, in bytes, of the target frame with respect to
   7.580 +	 * beginning of the first frame. */
   7.581 +
   7.582 +	unsigned frame_samples;
   7.583 +	/**< The number of samples in the target frame. */
   7.584 +} FLAC__StreamMetadata_SeekPoint;
   7.585 +
   7.586 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */
   7.587 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */
   7.588 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */
   7.589 +
   7.590 +/** The total stream length of a seek point in bytes. */
   7.591 +#define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
   7.592 +
   7.593 +/** The value used in the \a sample_number field of
   7.594 + *  FLAC__StreamMetadataSeekPoint used to indicate a placeholder
   7.595 + *  point (== 0xffffffffffffffff).
   7.596 + */
   7.597 +extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
   7.598 +
   7.599 +
   7.600 +/** FLAC SEEKTABLE structure.  (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>)
   7.601 + *
   7.602 + * \note From the format specification:
   7.603 + * - The seek points must be sorted by ascending sample number.
   7.604 + * - Each seek point's sample number must be the first sample of the
   7.605 + *   target frame.
   7.606 + * - Each seek point's sample number must be unique within the table.
   7.607 + * - Existence of a SEEKTABLE block implies a correct setting of
   7.608 + *   total_samples in the stream_info block.
   7.609 + * - Behavior is undefined when more than one SEEKTABLE block is
   7.610 + *   present in a stream.
   7.611 + */
   7.612 +typedef struct {
   7.613 +	unsigned num_points;
   7.614 +	FLAC__StreamMetadata_SeekPoint *points;
   7.615 +} FLAC__StreamMetadata_SeekTable;
   7.616 +
   7.617 +
   7.618 +/** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
   7.619 + *
   7.620 + *  For convenience, the APIs maintain a trailing NUL character at the end of
   7.621 + *  \a entry which is not counted toward \a length, i.e.
   7.622 + *  \code strlen(entry) == length \endcode
   7.623 + */
   7.624 +typedef struct {
   7.625 +	FLAC__uint32 length;
   7.626 +	FLAC__byte *entry;
   7.627 +} FLAC__StreamMetadata_VorbisComment_Entry;
   7.628 +
   7.629 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */
   7.630 +
   7.631 +
   7.632 +/** FLAC VORBIS_COMMENT structure.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
   7.633 + */
   7.634 +typedef struct {
   7.635 +	FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
   7.636 +	FLAC__uint32 num_comments;
   7.637 +	FLAC__StreamMetadata_VorbisComment_Entry *comments;
   7.638 +} FLAC__StreamMetadata_VorbisComment;
   7.639 +
   7.640 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
   7.641 +
   7.642 +
   7.643 +/** FLAC CUESHEET track index structure.  (See the
   7.644 + * <A HREF="../format.html#cuesheet_track_index">format specification</A> for
   7.645 + * the full description of each field.)
   7.646 + */
   7.647 +typedef struct {
   7.648 +	FLAC__uint64 offset;
   7.649 +	/**< Offset in samples, relative to the track offset, of the index
   7.650 +	 * point.
   7.651 +	 */
   7.652 +
   7.653 +	FLAC__byte number;
   7.654 +	/**< The index point number. */
   7.655 +} FLAC__StreamMetadata_CueSheet_Index;
   7.656 +
   7.657 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
   7.658 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */
   7.659 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */
   7.660 +
   7.661 +
   7.662 +/** FLAC CUESHEET track structure.  (See the
   7.663 + * <A HREF="../format.html#cuesheet_track">format specification</A> for
   7.664 + * the full description of each field.)
   7.665 + */
   7.666 +typedef struct {
   7.667 +	FLAC__uint64 offset;
   7.668 +	/**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
   7.669 +
   7.670 +	FLAC__byte number;
   7.671 +	/**< The track number. */
   7.672 +
   7.673 +	char isrc[13];
   7.674 +	/**< Track ISRC.  This is a 12-digit alphanumeric code plus a trailing \c NUL byte */
   7.675 +
   7.676 +	unsigned type:1;
   7.677 +	/**< The track type: 0 for audio, 1 for non-audio. */
   7.678 +
   7.679 +	unsigned pre_emphasis:1;
   7.680 +	/**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
   7.681 +
   7.682 +	FLAC__byte num_indices;
   7.683 +	/**< The number of track index points. */
   7.684 +
   7.685 +	FLAC__StreamMetadata_CueSheet_Index *indices;
   7.686 +	/**< NULL if num_indices == 0, else pointer to array of index points. */
   7.687 +
   7.688 +} FLAC__StreamMetadata_CueSheet_Track;
   7.689 +
   7.690 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
   7.691 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */
   7.692 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */
   7.693 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */
   7.694 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */
   7.695 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */
   7.696 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
   7.697 +
   7.698 +
   7.699 +/** FLAC CUESHEET structure.  (See the
   7.700 + * <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
   7.701 + * for the full description of each field.)
   7.702 + */
   7.703 +typedef struct {
   7.704 +	char media_catalog_number[129];
   7.705 +	/**< Media catalog number, in ASCII printable characters 0x20-0x7e.  In
   7.706 +	 * general, the media catalog number may be 0 to 128 bytes long; any
   7.707 +	 * unused characters should be right-padded with NUL characters.
   7.708 +	 */
   7.709 +
   7.710 +	FLAC__uint64 lead_in;
   7.711 +	/**< The number of lead-in samples. */
   7.712 +
   7.713 +	FLAC__bool is_cd;
   7.714 +	/**< \c true if CUESHEET corresponds to a Compact Disc, else \c false. */
   7.715 +
   7.716 +	unsigned num_tracks;
   7.717 +	/**< The number of tracks. */
   7.718 +
   7.719 +	FLAC__StreamMetadata_CueSheet_Track *tracks;
   7.720 +	/**< NULL if num_tracks == 0, else pointer to array of tracks. */
   7.721 +
   7.722 +} FLAC__StreamMetadata_CueSheet;
   7.723 +
   7.724 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
   7.725 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */
   7.726 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */
   7.727 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */
   7.728 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
   7.729 +
   7.730 +
   7.731 +/** An enumeration of the PICTURE types (see FLAC__StreamMetadataPicture and id3 v2.4 APIC tag). */
   7.732 +typedef enum {
   7.733 +	FLAC__STREAM_METADATA_PICTURE_TYPE_OTHER = 0, /**< Other */
   7.734 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON_STANDARD = 1, /**< 32x32 pixels 'file icon' (PNG only) */
   7.735 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON = 2, /**< Other file icon */
   7.736 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FRONT_COVER = 3, /**< Cover (front) */
   7.737 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BACK_COVER = 4, /**< Cover (back) */
   7.738 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAFLET_PAGE = 5, /**< Leaflet page */
   7.739 +	FLAC__STREAM_METADATA_PICTURE_TYPE_MEDIA = 6, /**< Media (e.g. label side of CD) */
   7.740 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAD_ARTIST = 7, /**< Lead artist/lead performer/soloist */
   7.741 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ARTIST = 8, /**< Artist/performer */
   7.742 +	FLAC__STREAM_METADATA_PICTURE_TYPE_CONDUCTOR = 9, /**< Conductor */
   7.743 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND = 10, /**< Band/Orchestra */
   7.744 +	FLAC__STREAM_METADATA_PICTURE_TYPE_COMPOSER = 11, /**< Composer */
   7.745 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LYRICIST = 12, /**< Lyricist/text writer */
   7.746 +	FLAC__STREAM_METADATA_PICTURE_TYPE_RECORDING_LOCATION = 13, /**< Recording Location */
   7.747 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_RECORDING = 14, /**< During recording */
   7.748 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_PERFORMANCE = 15, /**< During performance */
   7.749 +	FLAC__STREAM_METADATA_PICTURE_TYPE_VIDEO_SCREEN_CAPTURE = 16, /**< Movie/video screen capture */
   7.750 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FISH = 17, /**< A bright coloured fish */
   7.751 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ILLUSTRATION = 18, /**< Illustration */
   7.752 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND_LOGOTYPE = 19, /**< Band/artist logotype */
   7.753 +	FLAC__STREAM_METADATA_PICTURE_TYPE_PUBLISHER_LOGOTYPE = 20, /**< Publisher/Studio logotype */
   7.754 +	FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED
   7.755 +} FLAC__StreamMetadata_Picture_Type;
   7.756 +
   7.757 +/** Maps a FLAC__StreamMetadata_Picture_Type to a C string.
   7.758 + *
   7.759 + *  Using a FLAC__StreamMetadata_Picture_Type as the index to this array
   7.760 + *  will give the string equivalent.  The contents should not be
   7.761 + *  modified.
   7.762 + */
   7.763 +extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[];
   7.764 +
   7.765 +/** FLAC PICTURE structure.  (See the
   7.766 + * <A HREF="../format.html#metadata_block_picture">format specification</A>
   7.767 + * for the full description of each field.)
   7.768 + */
   7.769 +typedef struct {
   7.770 +	FLAC__StreamMetadata_Picture_Type type;
   7.771 +	/**< The kind of picture stored. */
   7.772 +
   7.773 +	char *mime_type;
   7.774 +	/**< Picture data's MIME type, in ASCII printable characters
   7.775 +	 * 0x20-0x7e, NUL terminated.  For best compatibility with players,
   7.776 +	 * use picture data of MIME type \c image/jpeg or \c image/png.  A
   7.777 +	 * MIME type of '-->' is also allowed, in which case the picture
   7.778 +	 * data should be a complete URL.  In file storage, the MIME type is
   7.779 +	 * stored as a 32-bit length followed by the ASCII string with no NUL
   7.780 +	 * terminator, but is converted to a plain C string in this structure
   7.781 +	 * for convenience.
   7.782 +	 */
   7.783 +
   7.784 +	FLAC__byte *description;
   7.785 +	/**< Picture's description in UTF-8, NUL terminated.  In file storage,
   7.786 +	 * the description is stored as a 32-bit length followed by the UTF-8
   7.787 +	 * string with no NUL terminator, but is converted to a plain C string
   7.788 +	 * in this structure for convenience.
   7.789 +	 */
   7.790 +
   7.791 +	FLAC__uint32 width;
   7.792 +	/**< Picture's width in pixels. */
   7.793 +
   7.794 +	FLAC__uint32 height;
   7.795 +	/**< Picture's height in pixels. */
   7.796 +
   7.797 +	FLAC__uint32 depth;
   7.798 +	/**< Picture's color depth in bits-per-pixel. */
   7.799 +
   7.800 +	FLAC__uint32 colors;
   7.801 +	/**< For indexed palettes (like GIF), picture's number of colors (the
   7.802 +	 * number of palette entries), or \c 0 for non-indexed (i.e. 2^depth).
   7.803 +	 */
   7.804 +
   7.805 +	FLAC__uint32 data_length;
   7.806 +	/**< Length of binary picture data in bytes. */
   7.807 +
   7.808 +	FLAC__byte *data;
   7.809 +	/**< Binary picture data. */
   7.810 +
   7.811 +} FLAC__StreamMetadata_Picture;
   7.812 +
   7.813 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN; /**< == 32 (bits) */
   7.814 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN; /**< == 32 (bits) */
   7.815 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN; /**< == 32 (bits) */
   7.816 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN; /**< == 32 (bits) */
   7.817 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN; /**< == 32 (bits) */
   7.818 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN; /**< == 32 (bits) */
   7.819 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN; /**< == 32 (bits) */
   7.820 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN; /**< == 32 (bits) */
   7.821 +
   7.822 +
   7.823 +/** Structure that is used when a metadata block of unknown type is loaded.
   7.824 + *  The contents are opaque.  The structure is used only internally to
   7.825 + *  correctly handle unknown metadata.
   7.826 + */
   7.827 +typedef struct {
   7.828 +	FLAC__byte *data;
   7.829 +} FLAC__StreamMetadata_Unknown;
   7.830 +
   7.831 +
   7.832 +/** FLAC metadata block structure.  (c.f. <A HREF="../format.html#metadata_block">format specification</A>)
   7.833 + */
   7.834 +typedef struct {
   7.835 +	FLAC__MetadataType type;
   7.836 +	/**< The type of the metadata block; used determine which member of the
   7.837 +	 * \a data union to dereference.  If type >= FLAC__METADATA_TYPE_UNDEFINED
   7.838 +	 * then \a data.unknown must be used. */
   7.839 +
   7.840 +	FLAC__bool is_last;
   7.841 +	/**< \c true if this metadata block is the last, else \a false */
   7.842 +
   7.843 +	unsigned length;
   7.844 +	/**< Length, in bytes, of the block data as it appears in the stream. */
   7.845 +
   7.846 +	union {
   7.847 +		FLAC__StreamMetadata_StreamInfo stream_info;
   7.848 +		FLAC__StreamMetadata_Padding padding;
   7.849 +		FLAC__StreamMetadata_Application application;
   7.850 +		FLAC__StreamMetadata_SeekTable seek_table;
   7.851 +		FLAC__StreamMetadata_VorbisComment vorbis_comment;
   7.852 +		FLAC__StreamMetadata_CueSheet cue_sheet;
   7.853 +		FLAC__StreamMetadata_Picture picture;
   7.854 +		FLAC__StreamMetadata_Unknown unknown;
   7.855 +	} data;
   7.856 +	/**< Polymorphic block data; use the \a type value to determine which
   7.857 +	 * to use. */
   7.858 +} FLAC__StreamMetadata;
   7.859 +
   7.860 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */
   7.861 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */
   7.862 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */
   7.863 +
   7.864 +/** The total stream length of a metadata block header in bytes. */
   7.865 +#define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
   7.866 +
   7.867 +/*****************************************************************************/
   7.868 +
   7.869 +
   7.870 +/*****************************************************************************
   7.871 + *
   7.872 + * Utility functions
   7.873 + *
   7.874 + *****************************************************************************/
   7.875 +
   7.876 +/** Tests that a sample rate is valid for FLAC.
   7.877 + *
   7.878 + * \param sample_rate  The sample rate to test for compliance.
   7.879 + * \retval FLAC__bool
   7.880 + *    \c true if the given sample rate conforms to the specification, else
   7.881 + *    \c false.
   7.882 + */
   7.883 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
   7.884 +
   7.885 +/** Tests that a sample rate is valid for the FLAC subset.  The subset rules
   7.886 + *  for valid sample rates are slightly more complex since the rate has to
   7.887 + *  be expressible completely in the frame header.
   7.888 + *
   7.889 + * \param sample_rate  The sample rate to test for compliance.
   7.890 + * \retval FLAC__bool
   7.891 + *    \c true if the given sample rate conforms to the specification for the
   7.892 + *    subset, else \c false.
   7.893 + */
   7.894 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate);
   7.895 +
   7.896 +/** Check a Vorbis comment entry name to see if it conforms to the Vorbis
   7.897 + *  comment specification.
   7.898 + *
   7.899 + *  Vorbis comment names must be composed only of characters from
   7.900 + *  [0x20-0x3C,0x3E-0x7D].
   7.901 + *
   7.902 + * \param name       A NUL-terminated string to be checked.
   7.903 + * \assert
   7.904 + *    \code name != NULL \endcode
   7.905 + * \retval FLAC__bool
   7.906 + *    \c false if entry name is illegal, else \c true.
   7.907 + */
   7.908 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name);
   7.909 +
   7.910 +/** Check a Vorbis comment entry value to see if it conforms to the Vorbis
   7.911 + *  comment specification.
   7.912 + *
   7.913 + *  Vorbis comment values must be valid UTF-8 sequences.
   7.914 + *
   7.915 + * \param value      A string to be checked.
   7.916 + * \param length     A the length of \a value in bytes.  May be
   7.917 + *                   \c (unsigned)(-1) to indicate that \a value is a plain
   7.918 + *                   UTF-8 NUL-terminated string.
   7.919 + * \assert
   7.920 + *    \code value != NULL \endcode
   7.921 + * \retval FLAC__bool
   7.922 + *    \c false if entry name is illegal, else \c true.
   7.923 + */
   7.924 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length);
   7.925 +
   7.926 +/** Check a Vorbis comment entry to see if it conforms to the Vorbis
   7.927 + *  comment specification.
   7.928 + *
   7.929 + *  Vorbis comment entries must be of the form 'name=value', and 'name' and
   7.930 + *  'value' must be legal according to
   7.931 + *  FLAC__format_vorbiscomment_entry_name_is_legal() and
   7.932 + *  FLAC__format_vorbiscomment_entry_value_is_legal() respectively.
   7.933 + *
   7.934 + * \param entry      An entry to be checked.
   7.935 + * \param length     The length of \a entry in bytes.
   7.936 + * \assert
   7.937 + *    \code value != NULL \endcode
   7.938 + * \retval FLAC__bool
   7.939 + *    \c false if entry name is illegal, else \c true.
   7.940 + */
   7.941 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length);
   7.942 +
   7.943 +/** Check a seek table to see if it conforms to the FLAC specification.
   7.944 + *  See the format specification for limits on the contents of the
   7.945 + *  seek table.
   7.946 + *
   7.947 + * \param seek_table  A pointer to a seek table to be checked.
   7.948 + * \assert
   7.949 + *    \code seek_table != NULL \endcode
   7.950 + * \retval FLAC__bool
   7.951 + *    \c false if seek table is illegal, else \c true.
   7.952 + */
   7.953 +FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
   7.954 +
   7.955 +/** Sort a seek table's seek points according to the format specification.
   7.956 + *  This includes a "unique-ification" step to remove duplicates, i.e.
   7.957 + *  seek points with identical \a sample_number values.  Duplicate seek
   7.958 + *  points are converted into placeholder points and sorted to the end of
   7.959 + *  the table.
   7.960 + *
   7.961 + * \param seek_table  A pointer to a seek table to be sorted.
   7.962 + * \assert
   7.963 + *    \code seek_table != NULL \endcode
   7.964 + * \retval unsigned
   7.965 + *    The number of duplicate seek points converted into placeholders.
   7.966 + */
   7.967 +FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
   7.968 +
   7.969 +/** Check a cue sheet to see if it conforms to the FLAC specification.
   7.970 + *  See the format specification for limits on the contents of the
   7.971 + *  cue sheet.
   7.972 + *
   7.973 + * \param cue_sheet  A pointer to an existing cue sheet to be checked.
   7.974 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
   7.975 + *                   stringent requirements for a CD-DA (audio) disc.
   7.976 + * \param violation  Address of a pointer to a string.  If there is a
   7.977 + *                   violation, a pointer to a string explanation of the
   7.978 + *                   violation will be returned here. \a violation may be
   7.979 + *                   \c NULL if you don't need the returned string.  Do not
   7.980 + *                   free the returned string; it will always point to static
   7.981 + *                   data.
   7.982 + * \assert
   7.983 + *    \code cue_sheet != NULL \endcode
   7.984 + * \retval FLAC__bool
   7.985 + *    \c false if cue sheet is illegal, else \c true.
   7.986 + */
   7.987 +FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
   7.988 +
   7.989 +/** Check picture data to see if it conforms to the FLAC specification.
   7.990 + *  See the format specification for limits on the contents of the
   7.991 + *  PICTURE block.
   7.992 + *
   7.993 + * \param picture    A pointer to existing picture data to be checked.
   7.994 + * \param violation  Address of a pointer to a string.  If there is a
   7.995 + *                   violation, a pointer to a string explanation of the
   7.996 + *                   violation will be returned here. \a violation may be
   7.997 + *                   \c NULL if you don't need the returned string.  Do not
   7.998 + *                   free the returned string; it will always point to static
   7.999 + *                   data.
  7.1000 + * \assert
  7.1001 + *    \code picture != NULL \endcode
  7.1002 + * \retval FLAC__bool
  7.1003 + *    \c false if picture data is illegal, else \c true.
  7.1004 + */
  7.1005 +FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation);
  7.1006 +
  7.1007 +/* \} */
  7.1008 +
  7.1009 +#ifdef __cplusplus
  7.1010 +}
  7.1011 +#endif
  7.1012 +
  7.1013 +#endif
     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/VisualC/external/include/FLAC/metadata.h	Mon Jan 09 04:20:54 2012 -0500
     8.3 @@ -0,0 +1,2181 @@
     8.4 +/* libFLAC - Free Lossless Audio Codec library
     8.5 + * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     8.6 + *
     8.7 + * Redistribution and use in source and binary forms, with or without
     8.8 + * modification, are permitted provided that the following conditions
     8.9 + * are met:
    8.10 + *
    8.11 + * - Redistributions of source code must retain the above copyright
    8.12 + * notice, this list of conditions and the following disclaimer.
    8.13 + *
    8.14 + * - Redistributions in binary form must reproduce the above copyright
    8.15 + * notice, this list of conditions and the following disclaimer in the
    8.16 + * documentation and/or other materials provided with the distribution.
    8.17 + *
    8.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    8.19 + * contributors may be used to endorse or promote products derived from
    8.20 + * this software without specific prior written permission.
    8.21 + *
    8.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    8.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    8.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    8.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    8.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    8.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    8.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    8.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    8.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    8.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    8.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    8.33 + */
    8.34 +
    8.35 +#ifndef FLAC__METADATA_H
    8.36 +#define FLAC__METADATA_H
    8.37 +
    8.38 +#include <sys/types.h> /* for off_t */
    8.39 +#include "export.h"
    8.40 +#include "callback.h"
    8.41 +#include "format.h"
    8.42 +
    8.43 +/* --------------------------------------------------------------------
    8.44 +   (For an example of how all these routines are used, see the source
    8.45 +   code for the unit tests in src/test_libFLAC/metadata_*.c, or
    8.46 +   metaflac in src/metaflac/)
    8.47 +   ------------------------------------------------------------------*/
    8.48 +
    8.49 +/** \file include/FLAC/metadata.h
    8.50 + *
    8.51 + *  \brief
    8.52 + *  This module provides functions for creating and manipulating FLAC
    8.53 + *  metadata blocks in memory, and three progressively more powerful
    8.54 + *  interfaces for traversing and editing metadata in FLAC files.
    8.55 + *
    8.56 + *  See the detailed documentation for each interface in the
    8.57 + *  \link flac_metadata metadata \endlink module.
    8.58 + */
    8.59 +
    8.60 +/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
    8.61 + *  \ingroup flac
    8.62 + *
    8.63 + *  \brief
    8.64 + *  This module provides functions for creating and manipulating FLAC
    8.65 + *  metadata blocks in memory, and three progressively more powerful
    8.66 + *  interfaces for traversing and editing metadata in native FLAC files.
    8.67 + *  Note that currently only the Chain interface (level 2) supports Ogg
    8.68 + *  FLAC files, and it is read-only i.e. no writing back changed
    8.69 + *  metadata to file.
    8.70 + *
    8.71 + *  There are three metadata interfaces of increasing complexity:
    8.72 + *
    8.73 + *  Level 0:
    8.74 + *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
    8.75 + *  PICTURE blocks.
    8.76 + *
    8.77 + *  Level 1:
    8.78 + *  Read-write access to all metadata blocks.  This level is write-
    8.79 + *  efficient in most cases (more on this below), and uses less memory
    8.80 + *  than level 2.
    8.81 + *
    8.82 + *  Level 2:
    8.83 + *  Read-write access to all metadata blocks.  This level is write-
    8.84 + *  efficient in all cases, but uses more memory since all metadata for
    8.85 + *  the whole file is read into memory and manipulated before writing
    8.86 + *  out again.
    8.87 + *
    8.88 + *  What do we mean by efficient?  Since FLAC metadata appears at the
    8.89 + *  beginning of the file, when writing metadata back to a FLAC file
    8.90 + *  it is possible to grow or shrink the metadata such that the entire
    8.91 + *  file must be rewritten.  However, if the size remains the same during
    8.92 + *  changes or PADDING blocks are utilized, only the metadata needs to be
    8.93 + *  overwritten, which is much faster.
    8.94 + *
    8.95 + *  Efficient means the whole file is rewritten at most one time, and only
    8.96 + *  when necessary.  Level 1 is not efficient only in the case that you
    8.97 + *  cause more than one metadata block to grow or shrink beyond what can
    8.98 + *  be accomodated by padding.  In this case you should probably use level
    8.99 + *  2, which allows you to edit all the metadata for a file in memory and
   8.100 + *  write it out all at once.
   8.101 + *
   8.102 + *  All levels know how to skip over and not disturb an ID3v2 tag at the
   8.103 + *  front of the file.
   8.104 + *
   8.105 + *  All levels access files via their filenames.  In addition, level 2
   8.106 + *  has additional alternative read and write functions that take an I/O
   8.107 + *  handle and callbacks, for situations where access by filename is not
   8.108 + *  possible.
   8.109 + *
   8.110 + *  In addition to the three interfaces, this module defines functions for
   8.111 + *  creating and manipulating various metadata objects in memory.  As we see
   8.112 + *  from the Format module, FLAC metadata blocks in memory are very primitive
   8.113 + *  structures for storing information in an efficient way.  Reading
   8.114 + *  information from the structures is easy but creating or modifying them
   8.115 + *  directly is more complex.  The metadata object routines here facilitate
   8.116 + *  this by taking care of the consistency and memory management drudgery.
   8.117 + *
   8.118 + *  Unless you will be using the level 1 or 2 interfaces to modify existing
   8.119 + *  metadata however, you will not probably not need these.
   8.120 + *
   8.121 + *  From a dependency standpoint, none of the encoders or decoders require
   8.122 + *  the metadata module.  This is so that embedded users can strip out the
   8.123 + *  metadata module from libFLAC to reduce the size and complexity.
   8.124 + */
   8.125 +
   8.126 +#ifdef __cplusplus
   8.127 +extern "C" {
   8.128 +#endif
   8.129 +
   8.130 +
   8.131 +/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
   8.132 + *  \ingroup flac_metadata
   8.133 + *
   8.134 + *  \brief
   8.135 + *  The level 0 interface consists of individual routines to read the
   8.136 + *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
   8.137 + *  only a filename.
   8.138 + *
   8.139 + *  They try to skip any ID3v2 tag at the head of the file.
   8.140 + *
   8.141 + * \{
   8.142 + */
   8.143 +
   8.144 +/** Read the STREAMINFO metadata block of the given FLAC file.  This function
   8.145 + *  will try to skip any ID3v2 tag at the head of the file.
   8.146 + *
   8.147 + * \param filename    The path to the FLAC file to read.
   8.148 + * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
   8.149 + *                    FLAC__StreamMetadata is a simple structure with no
   8.150 + *                    memory allocation involved, you pass the address of
   8.151 + *                    an existing structure.  It need not be initialized.
   8.152 + * \assert
   8.153 + *    \code filename != NULL \endcode
   8.154 + *    \code streaminfo != NULL \endcode
   8.155 + * \retval FLAC__bool
   8.156 + *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
   8.157 + *    \c false if there was a memory allocation error, a file decoder error,
   8.158 + *    or the file contained no STREAMINFO block.  (A memory allocation error
   8.159 + *    is possible because this function must set up a file decoder.)
   8.160 + */
   8.161 +FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
   8.162 +
   8.163 +/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
   8.164 + *  function will try to skip any ID3v2 tag at the head of the file.
   8.165 + *
   8.166 + * \param filename    The path to the FLAC file to read.
   8.167 + * \param tags        The address where the returned pointer will be
   8.168 + *                    stored.  The \a tags object must be deleted by
   8.169 + *                    the caller using FLAC__metadata_object_delete().
   8.170 + * \assert
   8.171 + *    \code filename != NULL \endcode
   8.172 + *    \code tags != NULL \endcode
   8.173 + * \retval FLAC__bool
   8.174 + *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
   8.175 + *    and \a *tags will be set to the address of the metadata structure.
   8.176 + *    Returns \c false if there was a memory allocation error, a file
   8.177 + *    decoder error, or the file contained no VORBIS_COMMENT block, and
   8.178 + *    \a *tags will be set to \c NULL.
   8.179 + */
   8.180 +FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
   8.181 +
   8.182 +/** Read the CUESHEET metadata block of the given FLAC file.  This
   8.183 + *  function will try to skip any ID3v2 tag at the head of the file.
   8.184 + *
   8.185 + * \param filename    The path to the FLAC file to read.
   8.186 + * \param cuesheet    The address where the returned pointer will be
   8.187 + *                    stored.  The \a cuesheet object must be deleted by
   8.188 + *                    the caller using FLAC__metadata_object_delete().
   8.189 + * \assert
   8.190 + *    \code filename != NULL \endcode
   8.191 + *    \code cuesheet != NULL \endcode
   8.192 + * \retval FLAC__bool
   8.193 + *    \c true if a valid CUESHEET block was read from \a filename,
   8.194 + *    and \a *cuesheet will be set to the address of the metadata
   8.195 + *    structure.  Returns \c false if there was a memory allocation
   8.196 + *    error, a file decoder error, or the file contained no CUESHEET
   8.197 + *    block, and \a *cuesheet will be set to \c NULL.
   8.198 + */
   8.199 +FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
   8.200 +
   8.201 +/** Read a PICTURE metadata block of the given FLAC file.  This
   8.202 + *  function will try to skip any ID3v2 tag at the head of the file.
   8.203 + *  Since there can be more than one PICTURE block in a file, this
   8.204 + *  function takes a number of parameters that act as constraints to
   8.205 + *  the search.  The PICTURE block with the largest area matching all
   8.206 + *  the constraints will be returned, or \a *picture will be set to
   8.207 + *  \c NULL if there was no such block.
   8.208 + *
   8.209 + * \param filename    The path to the FLAC file to read.
   8.210 + * \param picture     The address where the returned pointer will be
   8.211 + *                    stored.  The \a picture object must be deleted by
   8.212 + *                    the caller using FLAC__metadata_object_delete().
   8.213 + * \param type        The desired picture type.  Use \c -1 to mean
   8.214 + *                    "any type".
   8.215 + * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
   8.216 + *                    string will be matched exactly.  Use \c NULL to
   8.217 + *                    mean "any MIME type".
   8.218 + * \param description The desired description.  The string will be
   8.219 + *                    matched exactly.  Use \c NULL to mean "any
   8.220 + *                    description".
   8.221 + * \param max_width   The maximum width in pixels desired.  Use
   8.222 + *                    \c (unsigned)(-1) to mean "any width".
   8.223 + * \param max_height  The maximum height in pixels desired.  Use
   8.224 + *                    \c (unsigned)(-1) to mean "any height".
   8.225 + * \param max_depth   The maximum color depth in bits-per-pixel desired.
   8.226 + *                    Use \c (unsigned)(-1) to mean "any depth".
   8.227 + * \param max_colors  The maximum number of colors desired.  Use
   8.228 + *                    \c (unsigned)(-1) to mean "any number of colors".
   8.229 + * \assert
   8.230 + *    \code filename != NULL \endcode
   8.231 + *    \code picture != NULL \endcode
   8.232 + * \retval FLAC__bool
   8.233 + *    \c true if a valid PICTURE block was read from \a filename,
   8.234 + *    and \a *picture will be set to the address of the metadata
   8.235 + *    structure.  Returns \c false if there was a memory allocation
   8.236 + *    error, a file decoder error, or the file contained no PICTURE
   8.237 + *    block, and \a *picture will be set to \c NULL.
   8.238 + */
   8.239 +FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors);
   8.240 +
   8.241 +/* \} */
   8.242 +
   8.243 +
   8.244 +/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
   8.245 + *  \ingroup flac_metadata
   8.246 + *
   8.247 + * \brief
   8.248 + * The level 1 interface provides read-write access to FLAC file metadata and
   8.249 + * operates directly on the FLAC file.
   8.250 + *
   8.251 + * The general usage of this interface is:
   8.252 + *
   8.253 + * - Create an iterator using FLAC__metadata_simple_iterator_new()
   8.254 + * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
   8.255 + *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
   8.256 + *   see if the file is writable, or only read access is allowed.
   8.257 + * - Use FLAC__metadata_simple_iterator_next() and
   8.258 + *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
   8.259 + *   This is does not read the actual blocks themselves.
   8.260 + *   FLAC__metadata_simple_iterator_next() is relatively fast.
   8.261 + *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
   8.262 + *   forward from the front of the file.
   8.263 + * - Use FLAC__metadata_simple_iterator_get_block_type() or
   8.264 + *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
   8.265 + *   the current iterator position.  The returned object is yours to modify
   8.266 + *   and free.
   8.267 + * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
   8.268 + *   back.  You must have write permission to the original file.  Make sure to
   8.269 + *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
   8.270 + *   below.
   8.271 + * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
   8.272 + *   Use the object creation functions from
   8.273 + *   \link flac_metadata_object here \endlink to generate new objects.
   8.274 + * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
   8.275 + *   currently referred to by the iterator, or replace it with padding.
   8.276 + * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
   8.277 + *   finished.
   8.278 + *
   8.279 + * \note
   8.280 + * The FLAC file remains open the whole time between
   8.281 + * FLAC__metadata_simple_iterator_init() and
   8.282 + * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
   8.283 + * the file during this time.
   8.284 + *
   8.285 + * \note
   8.286 + * Do not modify the \a is_last, \a length, or \a type fields of returned
   8.287 + * FLAC__StreamMetadata objects.  These are managed automatically.
   8.288 + *
   8.289 + * \note
   8.290 + * If any of the modification functions
   8.291 + * (FLAC__metadata_simple_iterator_set_block(),
   8.292 + * FLAC__metadata_simple_iterator_delete_block(),
   8.293 + * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
   8.294 + * you should delete the iterator as it may no longer be valid.
   8.295 + *
   8.296 + * \{
   8.297 + */
   8.298 +
   8.299 +struct FLAC__Metadata_SimpleIterator;
   8.300 +/** The opaque structure definition for the level 1 iterator type.
   8.301 + *  See the
   8.302 + *  \link flac_metadata_level1 metadata level 1 module \endlink
   8.303 + *  for a detailed description.
   8.304 + */
   8.305 +typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
   8.306 +
   8.307 +/** Status type for FLAC__Metadata_SimpleIterator.
   8.308 + *
   8.309 + *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
   8.310 + */
   8.311 +typedef enum {
   8.312 +
   8.313 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
   8.314 +	/**< The iterator is in the normal OK state */
   8.315 +
   8.316 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
   8.317 +	/**< The data passed into a function violated the function's usage criteria */
   8.318 +
   8.319 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
   8.320 +	/**< The iterator could not open the target file */
   8.321 +
   8.322 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
   8.323 +	/**< The iterator could not find the FLAC signature at the start of the file */
   8.324 +
   8.325 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
   8.326 +	/**< The iterator tried to write to a file that was not writable */
   8.327 +
   8.328 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
   8.329 +	/**< The iterator encountered input that does not conform to the FLAC metadata specification */
   8.330 +
   8.331 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
   8.332 +	/**< The iterator encountered an error while reading the FLAC file */
   8.333 +
   8.334 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
   8.335 +	/**< The iterator encountered an error while seeking in the FLAC file */
   8.336 +
   8.337 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
   8.338 +	/**< The iterator encountered an error while writing the FLAC file */
   8.339 +
   8.340 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
   8.341 +	/**< The iterator encountered an error renaming the FLAC file */
   8.342 +
   8.343 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
   8.344 +	/**< The iterator encountered an error removing the temporary file */
   8.345 +
   8.346 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
   8.347 +	/**< Memory allocation failed */
   8.348 +
   8.349 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
   8.350 +	/**< The caller violated an assertion or an unexpected error occurred */
   8.351 +
   8.352 +} FLAC__Metadata_SimpleIteratorStatus;
   8.353 +
   8.354 +/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
   8.355 + *
   8.356 + *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
   8.357 + *  will give the string equivalent.  The contents should not be modified.
   8.358 + */
   8.359 +extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
   8.360 +
   8.361 +
   8.362 +/** Create a new iterator instance.
   8.363 + *
   8.364 + * \retval FLAC__Metadata_SimpleIterator*
   8.365 + *    \c NULL if there was an error allocating memory, else the new instance.
   8.366 + */
   8.367 +FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
   8.368 +
   8.369 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
   8.370 + *
   8.371 + * \param iterator  A pointer to an existing iterator.
   8.372 + * \assert
   8.373 + *    \code iterator != NULL \endcode
   8.374 + */
   8.375 +FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
   8.376 +
   8.377 +/** Get the current status of the iterator.  Call this after a function
   8.378 + *  returns \c false to get the reason for the error.  Also resets the status
   8.379 + *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
   8.380 + *
   8.381 + * \param iterator  A pointer to an existing iterator.
   8.382 + * \assert
   8.383 + *    \code iterator != NULL \endcode
   8.384 + * \retval FLAC__Metadata_SimpleIteratorStatus
   8.385 + *    The current status of the iterator.
   8.386 + */
   8.387 +FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
   8.388 +
   8.389 +/** Initialize the iterator to point to the first metadata block in the
   8.390 + *  given FLAC file.
   8.391 + *
   8.392 + * \param iterator             A pointer to an existing iterator.
   8.393 + * \param filename             The path to the FLAC file.
   8.394 + * \param read_only            If \c true, the FLAC file will be opened
   8.395 + *                             in read-only mode; if \c false, the FLAC
   8.396 + *                             file will be opened for edit even if no
   8.397 + *                             edits are performed.
   8.398 + * \param preserve_file_stats  If \c true, the owner and modification
   8.399 + *                             time will be preserved even if the FLAC
   8.400 + *                             file is written to.
   8.401 + * \assert
   8.402 + *    \code iterator != NULL \endcode
   8.403 + *    \code filename != NULL \endcode
   8.404 + * \retval FLAC__bool
   8.405 + *    \c false if a memory allocation error occurs, the file can't be
   8.406 + *    opened, or another error occurs, else \c true.
   8.407 + */
   8.408 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats);
   8.409 +
   8.410 +/** Returns \c true if the FLAC file is writable.  If \c false, calls to
   8.411 + *  FLAC__metadata_simple_iterator_set_block() and
   8.412 + *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
   8.413 + *
   8.414 + * \param iterator             A pointer to an existing iterator.
   8.415 + * \assert
   8.416 + *    \code iterator != NULL \endcode
   8.417 + * \retval FLAC__bool
   8.418 + *    See above.
   8.419 + */
   8.420 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
   8.421 +
   8.422 +/** Moves the iterator forward one metadata block, returning \c false if
   8.423 + *  already at the end.
   8.424 + *
   8.425 + * \param iterator  A pointer to an existing initialized iterator.
   8.426 + * \assert
   8.427 + *    \code iterator != NULL \endcode
   8.428 + *    \a iterator has been successfully initialized with
   8.429 + *    FLAC__metadata_simple_iterator_init()
   8.430 + * \retval FLAC__bool
   8.431 + *    \c false if already at the last metadata block of the chain, else
   8.432 + *    \c true.
   8.433 + */
   8.434 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
   8.435 +
   8.436 +/** Moves the iterator backward one metadata block, returning \c false if
   8.437 + *  already at the beginning.
   8.438 + *
   8.439 + * \param iterator  A pointer to an existing initialized iterator.
   8.440 + * \assert
   8.441 + *    \code iterator != NULL \endcode
   8.442 + *    \a iterator has been successfully initialized with
   8.443 + *    FLAC__metadata_simple_iterator_init()
   8.444 + * \retval FLAC__bool
   8.445 + *    \c false if already at the first metadata block of the chain, else
   8.446 + *    \c true.
   8.447 + */
   8.448 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
   8.449 +
   8.450 +/** Returns a flag telling if the current metadata block is the last.
   8.451 + *
   8.452 + * \param iterator  A pointer to an existing initialized iterator.
   8.453 + * \assert
   8.454 + *    \code iterator != NULL \endcode
   8.455 + *    \a iterator has been successfully initialized with
   8.456 + *    FLAC__metadata_simple_iterator_init()
   8.457 + * \retval FLAC__bool
   8.458 + *    \c true if the current metadata block is the last in the file,
   8.459 + *    else \c false.
   8.460 + */
   8.461 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
   8.462 +
   8.463 +/** Get the offset of the metadata block at the current position.  This
   8.464 + *  avoids reading the actual block data which can save time for large
   8.465 + *  blocks.
   8.466 + *
   8.467 + * \param iterator  A pointer to an existing initialized iterator.
   8.468 + * \assert
   8.469 + *    \code iterator != NULL \endcode
   8.470 + *    \a iterator has been successfully initialized with
   8.471 + *    FLAC__metadata_simple_iterator_init()
   8.472 + * \retval off_t
   8.473 + *    The offset of the metadata block at the current iterator position.
   8.474 + *    This is the byte offset relative to the beginning of the file of
   8.475 + *    the current metadata block's header.
   8.476 + */
   8.477 +FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
   8.478 +
   8.479 +/** Get the type of the metadata block at the current position.  This
   8.480 + *  avoids reading the actual block data which can save time for large
   8.481 + *  blocks.
   8.482 + *
   8.483 + * \param iterator  A pointer to an existing initialized iterator.
   8.484 + * \assert
   8.485 + *    \code iterator != NULL \endcode
   8.486 + *    \a iterator has been successfully initialized with
   8.487 + *    FLAC__metadata_simple_iterator_init()
   8.488 + * \retval FLAC__MetadataType
   8.489 + *    The type of the metadata block at the current iterator position.
   8.490 + */
   8.491 +FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
   8.492 +
   8.493 +/** Get the length of the metadata block at the current position.  This
   8.494 + *  avoids reading the actual block data which can save time for large
   8.495 + *  blocks.
   8.496 + *
   8.497 + * \param iterator  A pointer to an existing initialized iterator.
   8.498 + * \assert
   8.499 + *    \code iterator != NULL \endcode
   8.500 + *    \a iterator has been successfully initialized with
   8.501 + *    FLAC__metadata_simple_iterator_init()
   8.502 + * \retval unsigned
   8.503 + *    The length of the metadata block at the current iterator position.
   8.504 + *    The is same length as that in the
   8.505 + *    <a href="http://flac.sourceforge.net/format.html#metadata_block_header">metadata block header</a>,
   8.506 + *    i.e. the length of the metadata body that follows the header.
   8.507 + */
   8.508 +FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
   8.509 +
   8.510 +/** Get the application ID of the \c APPLICATION block at the current
   8.511 + *  position.  This avoids reading the actual block data which can save
   8.512 + *  time for large blocks.
   8.513 + *
   8.514 + * \param iterator  A pointer to an existing initialized iterator.
   8.515 + * \param id        A pointer to a buffer of at least \c 4 bytes where
   8.516 + *                  the ID will be stored.
   8.517 + * \assert
   8.518 + *    \code iterator != NULL \endcode
   8.519 + *    \code id != NULL \endcode
   8.520 + *    \a iterator has been successfully initialized with
   8.521 + *    FLAC__metadata_simple_iterator_init()
   8.522 + * \retval FLAC__bool
   8.523 + *    \c true if the ID was successfully read, else \c false, in which
   8.524 + *    case you should check FLAC__metadata_simple_iterator_status() to
   8.525 + *    find out why.  If the status is
   8.526 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the
   8.527 + *    current metadata block is not an \c APPLICATION block.  Otherwise
   8.528 + *    if the status is
   8.529 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or
   8.530 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error
   8.531 + *    occurred and the iterator can no longer be used.
   8.532 + */
   8.533 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
   8.534 +
   8.535 +/** Get the metadata block at the current position.  You can modify the
   8.536 + *  block but must use FLAC__metadata_simple_iterator_set_block() to
   8.537 + *  write it back to the FLAC file.
   8.538 + *
   8.539 + *  You must call FLAC__metadata_object_delete() on the returned object
   8.540 + *  when you are finished with it.
   8.541 + *
   8.542 + * \param iterator  A pointer to an existing initialized iterator.
   8.543 + * \assert
   8.544 + *    \code iterator != NULL \endcode
   8.545 + *    \a iterator has been successfully initialized with
   8.546 + *    FLAC__metadata_simple_iterator_init()
   8.547 + * \retval FLAC__StreamMetadata*
   8.548 + *    The current metadata block, or \c NULL if there was a memory
   8.549 + *    allocation error.
   8.550 + */
   8.551 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
   8.552 +
   8.553 +/** Write a block back to the FLAC file.  This function tries to be
   8.554 + *  as efficient as possible; how the block is actually written is
   8.555 + *  shown by the following:
   8.556 + *
   8.557 + *  Existing block is a STREAMINFO block and the new block is a
   8.558 + *  STREAMINFO block: the new block is written in place.  Make sure
   8.559 + *  you know what you're doing when changing the values of a
   8.560 + *  STREAMINFO block.
   8.561 + *
   8.562 + *  Existing block is a STREAMINFO block and the new block is a
   8.563 + *  not a STREAMINFO block: this is an error since the first block
   8.564 + *  must be a STREAMINFO block.  Returns \c false without altering the
   8.565 + *  file.
   8.566 + *
   8.567 + *  Existing block is not a STREAMINFO block and the new block is a
   8.568 + *  STREAMINFO block: this is an error since there may be only one
   8.569 + *  STREAMINFO block.  Returns \c false without altering the file.
   8.570 + *
   8.571 + *  Existing block and new block are the same length: the existing
   8.572 + *  block will be replaced by the new block, written in place.
   8.573 + *
   8.574 + *  Existing block is longer than new block: if use_padding is \c true,
   8.575 + *  the existing block will be overwritten in place with the new
   8.576 + *  block followed by a PADDING block, if possible, to make the total
   8.577 + *  size the same as the existing block.  Remember that a padding
   8.578 + *  block requires at least four bytes so if the difference in size
   8.579 + *  between the new block and existing block is less than that, the
   8.580 + *  entire file will have to be rewritten, using the new block's
   8.581 + *  exact size.  If use_padding is \c false, the entire file will be
   8.582 + *  rewritten, replacing the existing block by the new block.
   8.583 + *
   8.584 + *  Existing block is shorter than new block: if use_padding is \c true,
   8.585 + *  the function will try and expand the new block into the following
   8.586 + *  PADDING block, if it exists and doing so won't shrink the PADDING
   8.587 + *  block to less than 4 bytes.  If there is no following PADDING
   8.588 + *  block, or it will shrink to less than 4 bytes, or use_padding is
   8.589 + *  \c false, the entire file is rewritten, replacing the existing block
   8.590 + *  with the new block.  Note that in this case any following PADDING
   8.591 + *  block is preserved as is.
   8.592 + *
   8.593 + *  After writing the block, the iterator will remain in the same
   8.594 + *  place, i.e. pointing to the new block.
   8.595 + *
   8.596 + * \param iterator     A pointer to an existing initialized iterator.
   8.597 + * \param block        The block to set.
   8.598 + * \param use_padding  See above.
   8.599 + * \assert
   8.600 + *    \code iterator != NULL \endcode
   8.601 + *    \a iterator has been successfully initialized with
   8.602 + *    FLAC__metadata_simple_iterator_init()
   8.603 + *    \code block != NULL \endcode
   8.604 + * \retval FLAC__bool
   8.605 + *    \c true if successful, else \c false.
   8.606 + */
   8.607 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
   8.608 +
   8.609 +/** This is similar to FLAC__metadata_simple_iterator_set_block()
   8.610 + *  except that instead of writing over an existing block, it appends
   8.611 + *  a block after the existing block.  \a use_padding is again used to
   8.612 + *  tell the function to try an expand into following padding in an
   8.613 + *  attempt to avoid rewriting the entire file.
   8.614 + *
   8.615 + *  This function will fail and return \c false if given a STREAMINFO
   8.616 + *  block.
   8.617 + *
   8.618 + *  After writing the block, the iterator will be pointing to the
   8.619 + *  new block.
   8.620 + *
   8.621 + * \param iterator     A pointer to an existing initialized iterator.
   8.622 + * \param block        The block to set.
   8.623 + * \param use_padding  See above.
   8.624 + * \assert
   8.625 + *    \code iterator != NULL \endcode
   8.626 + *    \a iterator has been successfully initialized with
   8.627 + *    FLAC__metadata_simple_iterator_init()
   8.628 + *    \code block != NULL \endcode
   8.629 + * \retval FLAC__bool
   8.630 + *    \c true if successful, else \c false.
   8.631 + */
   8.632 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
   8.633 +
   8.634 +/** Deletes the block at the current position.  This will cause the
   8.635 + *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
   8.636 + *  in which case the block will be replaced by an equal-sized PADDING
   8.637 + *  block.  The iterator will be left pointing to the block before the
   8.638 + *  one just deleted.
   8.639 + *
   8.640 + *  You may not delete the STREAMINFO block.
   8.641 + *
   8.642 + * \param iterator     A pointer to an existing initialized iterator.
   8.643 + * \param use_padding  See above.
   8.644 + * \assert
   8.645 + *    \code iterator != NULL \endcode
   8.646 + *    \a iterator has been successfully initialized with
   8.647 + *    FLAC__metadata_simple_iterator_init()
   8.648 + * \retval FLAC__bool
   8.649 + *    \c true if successful, else \c false.
   8.650 + */
   8.651 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
   8.652 +
   8.653 +/* \} */
   8.654 +
   8.655 +
   8.656 +/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
   8.657 + *  \ingroup flac_metadata
   8.658 + *
   8.659 + * \brief
   8.660 + * The level 2 interface provides read-write access to FLAC file metadata;
   8.661 + * all metadata is read into memory, operated on in memory, and then written
   8.662 + * to file, which is more efficient than level 1 when editing multiple blocks.
   8.663 + *
   8.664 + * Currently Ogg FLAC is supported for read only, via
   8.665 + * FLAC__metadata_chain_read_ogg() but a subsequent
   8.666 + * FLAC__metadata_chain_write() will fail.
   8.667 + *
   8.668 + * The general usage of this interface is:
   8.669 + *
   8.670 + * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
   8.671 + *   linked list of FLAC metadata blocks.
   8.672 + * - Read all metadata into the the chain from a FLAC file using
   8.673 + *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
   8.674 + *   check the status.
   8.675 + * - Optionally, consolidate the padding using
   8.676 + *   FLAC__metadata_chain_merge_padding() or
   8.677 + *   FLAC__metadata_chain_sort_padding().
   8.678 + * - Create a new iterator using FLAC__metadata_iterator_new()
   8.679 + * - Initialize the iterator to point to the first element in the chain
   8.680 + *   using FLAC__metadata_iterator_init()
   8.681 + * - Traverse the chain using FLAC__metadata_iterator_next and
   8.682 + *   FLAC__metadata_iterator_prev().
   8.683 + * - Get a block for reading or modification using
   8.684 + *   FLAC__metadata_iterator_get_block().  The pointer to the object
   8.685 + *   inside the chain is returned, so the block is yours to modify.
   8.686 + *   Changes will be reflected in the FLAC file when you write the
   8.687 + *   chain.  You can also add and delete blocks (see functions below).
   8.688 + * - When done, write out the chain using FLAC__metadata_chain_write().
   8.689 + *   Make sure to read the whole comment to the function below.
   8.690 + * - Delete the chain using FLAC__metadata_chain_delete().
   8.691 + *
   8.692 + * \note
   8.693 + * Even though the FLAC file is not open while the chain is being
   8.694 + * manipulated, you must not alter the file externally during
   8.695 + * this time.  The chain assumes the FLAC file will not change
   8.696 + * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
   8.697 + * and FLAC__metadata_chain_write().
   8.698 + *
   8.699 + * \note
   8.700 + * Do not modify the is_last, length, or type fields of returned
   8.701 + * FLAC__StreamMetadata objects.  These are managed automatically.
   8.702 + *
   8.703 + * \note
   8.704 + * The metadata objects returned by FLAC__metadata_iterator_get_block()
   8.705 + * are owned by the chain; do not FLAC__metadata_object_delete() them.
   8.706 + * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
   8.707 + * become owned by the chain and they will be deleted when the chain is
   8.708 + * deleted.
   8.709 + *
   8.710 + * \{
   8.711 + */
   8.712 +
   8.713 +struct FLAC__Metadata_Chain;
   8.714 +/** The opaque structure definition for the level 2 chain type.
   8.715 + */
   8.716 +typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
   8.717 +
   8.718 +struct FLAC__Metadata_Iterator;
   8.719 +/** The opaque structure definition for the level 2 iterator type.
   8.720 + */
   8.721 +typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
   8.722 +
   8.723 +typedef enum {
   8.724 +	FLAC__METADATA_CHAIN_STATUS_OK = 0,
   8.725 +	/**< The chain is in the normal OK state */
   8.726 +
   8.727 +	FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
   8.728 +	/**< The data passed into a function violated the function's usage criteria */
   8.729 +
   8.730 +	FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
   8.731 +	/**< The chain could not open the target file */
   8.732 +
   8.733 +	FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
   8.734 +	/**< The chain could not find the FLAC signature at the start of the file */
   8.735 +
   8.736 +	FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
   8.737 +	/**< The chain tried to write to a file that was not writable */
   8.738 +
   8.739 +	FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
   8.740 +	/**< The chain encountered input that does not conform to the FLAC metadata specification */
   8.741 +
   8.742 +	FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
   8.743 +	/**< The chain encountered an error while reading the FLAC file */
   8.744 +
   8.745 +	FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
   8.746 +	/**< The chain encountered an error while seeking in the FLAC file */
   8.747 +
   8.748 +	FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
   8.749 +	/**< The chain encountered an error while writing the FLAC file */
   8.750 +
   8.751 +	FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
   8.752 +	/**< The chain encountered an error renaming the FLAC file */
   8.753 +
   8.754 +	FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
   8.755 +	/**< The chain encountered an error removing the temporary file */
   8.756 +
   8.757 +	FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
   8.758 +	/**< Memory allocation failed */
   8.759 +
   8.760 +	FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
   8.761 +	/**< The caller violated an assertion or an unexpected error occurred */
   8.762 +
   8.763 +	FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
   8.764 +	/**< One or more of the required callbacks was NULL */
   8.765 +
   8.766 +	FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
   8.767 +	/**< FLAC__metadata_chain_write() was called on a chain read by
   8.768 +	 *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
   8.769 +	 *   or 
   8.770 +	 *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
   8.771 +	 *   was called on a chain read by
   8.772 +	 *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
   8.773 +	 *   Matching read/write methods must always be used. */
   8.774 +
   8.775 +	FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
   8.776 +	/**< FLAC__metadata_chain_write_with_callbacks() was called when the
   8.777 +	 *   chain write requires a tempfile; use
   8.778 +	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
   8.779 +	 *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
   8.780 +	 *   called when the chain write does not require a tempfile; use
   8.781 +	 *   FLAC__metadata_chain_write_with_callbacks() instead.
   8.782 +	 *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
   8.783 +	 *   before writing via callbacks. */
   8.784 +
   8.785 +} FLAC__Metadata_ChainStatus;
   8.786 +
   8.787 +/** Maps a FLAC__Metadata_ChainStatus to a C string.
   8.788 + *
   8.789 + *  Using a FLAC__Metadata_ChainStatus as the index to this array
   8.790 + *  will give the string equivalent.  The contents should not be modified.
   8.791 + */
   8.792 +extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
   8.793 +
   8.794 +/*********** FLAC__Metadata_Chain ***********/
   8.795 +
   8.796 +/** Create a new chain instance.
   8.797 + *
   8.798 + * \retval FLAC__Metadata_Chain*
   8.799 + *    \c NULL if there was an error allocating memory, else the new instance.
   8.800 + */
   8.801 +FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
   8.802 +
   8.803 +/** Free a chain instance.  Deletes the object pointed to by \a chain.
   8.804 + *
   8.805 + * \param chain  A pointer to an existing chain.
   8.806 + * \assert
   8.807 + *    \code chain != NULL \endcode
   8.808 + */
   8.809 +FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
   8.810 +
   8.811 +/** Get the current status of the chain.  Call this after a function
   8.812 + *  returns \c false to get the reason for the error.  Also resets the
   8.813 + *  status to FLAC__METADATA_CHAIN_STATUS_OK.
   8.814 + *
   8.815 + * \param chain    A pointer to an existing chain.
   8.816 + * \assert
   8.817 + *    \code chain != NULL \endcode
   8.818 + * \retval FLAC__Metadata_ChainStatus
   8.819 + *    The current status of the chain.
   8.820 + */
   8.821 +FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
   8.822 +
   8.823 +/** Read all metadata from a FLAC file into the chain.
   8.824 + *
   8.825 + * \param chain    A pointer to an existing chain.
   8.826 + * \param filename The path to the FLAC file to read.
   8.827 + * \assert
   8.828 + *    \code chain != NULL \endcode
   8.829 + *    \code filename != NULL \endcode
   8.830 + * \retval FLAC__bool
   8.831 + *    \c true if a valid list of metadata blocks was read from
   8.832 + *    \a filename, else \c false.  On failure, check the status with
   8.833 + *    FLAC__metadata_chain_status().
   8.834 + */
   8.835 +FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
   8.836 +
   8.837 +/** Read all metadata from an Ogg FLAC file into the chain.
   8.838 + *
   8.839 + * \note Ogg FLAC metadata data writing is not supported yet and
   8.840 + * FLAC__metadata_chain_write() will fail.
   8.841 + *
   8.842 + * \param chain    A pointer to an existing chain.
   8.843 + * \param filename The path to the Ogg FLAC file to read.
   8.844 + * \assert
   8.845 + *    \code chain != NULL \endcode
   8.846 + *    \code filename != NULL \endcode
   8.847 + * \retval FLAC__bool
   8.848 + *    \c true if a valid list of metadata blocks was read from
   8.849 + *    \a filename, else \c false.  On failure, check the status with
   8.850 + *    FLAC__metadata_chain_status().
   8.851 + */
   8.852 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
   8.853 +
   8.854 +/** Read all metadata from a FLAC stream into the chain via I/O callbacks.
   8.855 + *
   8.856 + *  The \a handle need only be open for reading, but must be seekable.
   8.857 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
   8.858 + *  for Windows).
   8.859 + *
   8.860 + * \param chain    A pointer to an existing chain.
   8.861 + * \param handle   The I/O handle of the FLAC stream to read.  The
   8.862 + *                 handle will NOT be closed after the metadata is read;
   8.863 + *                 that is the duty of the caller.
   8.864 + * \param callbacks
   8.865 + *                 A set of callbacks to use for I/O.  The mandatory
   8.866 + *                 callbacks are \a read, \a seek, and \a tell.
   8.867 + * \assert
   8.868 + *    \code chain != NULL \endcode
   8.869 + * \retval FLAC__bool
   8.870 + *    \c true if a valid list of metadata blocks was read from
   8.871 + *    \a handle, else \c false.  On failure, check the status with
   8.872 + *    FLAC__metadata_chain_status().
   8.873 + */
   8.874 +FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
   8.875 +
   8.876 +/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
   8.877 + *
   8.878 + *  The \a handle need only be open for reading, but must be seekable.
   8.879 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
   8.880 + *  for Windows).
   8.881 + *
   8.882 + * \note Ogg FLAC metadata data writing is not supported yet and
   8.883 + * FLAC__metadata_chain_write() will fail.
   8.884 + *
   8.885 + * \param chain    A pointer to an existing chain.
   8.886 + * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
   8.887 + *                 handle will NOT be closed after the metadata is read;
   8.888 + *                 that is the duty of the caller.
   8.889 + * \param callbacks
   8.890 + *                 A set of callbacks to use for I/O.  The mandatory
   8.891 + *                 callbacks are \a read, \a seek, and \a tell.
   8.892 + * \assert
   8.893 + *    \code chain != NULL \endcode
   8.894 + * \retval FLAC__bool
   8.895 + *    \c true if a valid list of metadata blocks was read from
   8.896 + *    \a handle, else \c false.  On failure, check the status with
   8.897 + *    FLAC__metadata_chain_status().
   8.898 + */
   8.899 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
   8.900 +
   8.901 +/** Checks if writing the given chain would require the use of a
   8.902 + *  temporary file, or if it could be written in place.
   8.903 + *
   8.904 + *  Under certain conditions, padding can be utilized so that writing
   8.905 + *  edited metadata back to the FLAC file does not require rewriting the
   8.906 + *  entire file.  If rewriting is required, then a temporary workfile is
   8.907 + *  required.  When writing metadata using callbacks, you must check
   8.908 + *  this function to know whether to call
   8.909 + *  FLAC__metadata_chain_write_with_callbacks() or
   8.910 + *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
   8.911 + *  writing with FLAC__metadata_chain_write(), the temporary file is
   8.912 + *  handled internally.
   8.913 + *
   8.914 + * \param chain    A pointer to an existing chain.
   8.915 + * \param use_padding
   8.916 + *                 Whether or not padding will be allowed to be used
   8.917 + *                 during the write.  The value of \a use_padding given
   8.918 + *                 here must match the value later passed to
   8.919 + *                 FLAC__metadata_chain_write_with_callbacks() or
   8.920 + *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
   8.921 + * \assert
   8.922 + *    \code chain != NULL \endcode
   8.923 + * \retval FLAC__bool
   8.924 + *    \c true if writing the current chain would require a tempfile, or
   8.925 + *    \c false if metadata can be written in place.
   8.926 + */
   8.927 +FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
   8.928 +
   8.929 +/** Write all metadata out to the FLAC file.  This function tries to be as
   8.930 + *  efficient as possible; how the metadata is actually written is shown by
   8.931 + *  the following:
   8.932 + *
   8.933 + *  If the current chain is the same size as the existing metadata, the new
   8.934 + *  data is written in place.
   8.935 + *
   8.936 + *  If the current chain is longer than the existing metadata, and
   8.937 + *  \a use_padding is \c true, and the last block is a PADDING block of
   8.938 + *  sufficient length, the function will truncate the final padding block
   8.939 + *  so that the overall size of the metadata is the same as the existing
   8.940 + *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
   8.941 + *  the above conditions are met, the entire FLAC file must be rewritten.
   8.942 + *  If you want to use padding this way it is a good idea to call
   8.943 + *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
   8.944 + *  amount of padding to work with, unless you need to preserve ordering
   8.945 + *  of the PADDING blocks for some reason.
   8.946 + *
   8.947 + *  If the current chain is shorter than the existing metadata, and
   8.948 + *  \a use_padding is \c true, and the final block is a PADDING block, the padding
   8.949 + *  is extended to make the overall size the same as the existing data.  If
   8.950 + *  \a use_padding is \c true and the last block is not a PADDING block, a new
   8.951 + *  PADDING block is added to the end of the new data to make it the same
   8.952 + *  size as the existing data (if possible, see the note to
   8.953 + *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
   8.954 + *  and the new data is written in place.  If none of the above apply or
   8.955 + *  \a use_padding is \c false, the entire FLAC file is rewritten.
   8.956 + *
   8.957 + *  If \a preserve_file_stats is \c true, the owner and modification time will
   8.958 + *  be preserved even if the FLAC file is written.
   8.959 + *
   8.960 + *  For this write function to be used, the chain must have been read with
   8.961 + *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
   8.962 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
   8.963 + *
   8.964 + * \param chain               A pointer to an existing chain.
   8.965 + * \param use_padding         See above.
   8.966 + * \param preserve_file_stats See above.
   8.967 + * \assert
   8.968 + *    \code chain != NULL \endcode
   8.969 + * \retval FLAC__bool
   8.970 + *    \c true if the write succeeded, else \c false.  On failure,
   8.971 + *    check the status with FLAC__metadata_chain_status().
   8.972 + */
   8.973 +FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
   8.974 +
   8.975 +/** Write all metadata out to a FLAC stream via callbacks.
   8.976 + *
   8.977 + *  (See FLAC__metadata_chain_write() for the details on how padding is
   8.978 + *  used to write metadata in place if possible.)
   8.979 + *
   8.980 + *  The \a handle must be open for updating and be seekable.  The
   8.981 + *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
   8.982 + *  for Windows).
   8.983 + *
   8.984 + *  For this write function to be used, the chain must have been read with
   8.985 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
   8.986 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
   8.987 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
   8.988 + *  \c false.
   8.989 + *
   8.990 + * \param chain        A pointer to an existing chain.
   8.991 + * \param use_padding  See FLAC__metadata_chain_write()
   8.992 + * \param handle       The I/O handle of the FLAC stream to write.  The
   8.993 + *                     handle will NOT be closed after the metadata is
   8.994 + *                     written; that is the duty of the caller.
   8.995 + * \param callbacks    A set of callbacks to use for I/O.  The mandatory
   8.996 + *                     callbacks are \a write and \a seek.
   8.997 + * \assert
   8.998 + *    \code chain != NULL \endcode
   8.999 + * \retval FLAC__bool
  8.1000 + *    \c true if the write succeeded, else \c false.  On failure,
  8.1001 + *    check the status with FLAC__metadata_chain_status().
  8.1002 + */
  8.1003 +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  8.1004 +
  8.1005 +/** Write all metadata out to a FLAC stream via callbacks.
  8.1006 + *
  8.1007 + *  (See FLAC__metadata_chain_write() for the details on how padding is
  8.1008 + *  used to write metadata in place if possible.)
  8.1009 + *
  8.1010 + *  This version of the write-with-callbacks function must be used when
  8.1011 + *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
  8.1012 + *  this function, you must supply an I/O handle corresponding to the
  8.1013 + *  FLAC file to edit, and a temporary handle to which the new FLAC
  8.1014 + *  file will be written.  It is the caller's job to move this temporary
  8.1015 + *  FLAC file on top of the original FLAC file to complete the metadata
  8.1016 + *  edit.
  8.1017 + *
  8.1018 + *  The \a handle must be open for reading and be seekable.  The
  8.1019 + *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  8.1020 + *  for Windows).
  8.1021 + *
  8.1022 + *  The \a temp_handle must be open for writing.  The
  8.1023 + *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
  8.1024 + *  for Windows).  It should be an empty stream, or at least positioned
  8.1025 + *  at the start-of-file (in which case it is the caller's duty to
  8.1026 + *  truncate it on return).
  8.1027 + *
  8.1028 + *  For this write function to be used, the chain must have been read with
  8.1029 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  8.1030 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  8.1031 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  8.1032 + *  \c true.
  8.1033 + *
  8.1034 + * \param chain        A pointer to an existing chain.
  8.1035 + * \param use_padding  See FLAC__metadata_chain_write()
  8.1036 + * \param handle       The I/O handle of the original FLAC stream to read.
  8.1037 + *                     The handle will NOT be closed after the metadata is
  8.1038 + *                     written; that is the duty of the caller.
  8.1039 + * \param callbacks    A set of callbacks to use for I/O on \a handle.
  8.1040 + *                     The mandatory callbacks are \a read, \a seek, and
  8.1041 + *                     \a eof.
  8.1042 + * \param temp_handle  The I/O handle of the FLAC stream to write.  The
  8.1043 + *                     handle will NOT be closed after the metadata is
  8.1044 + *                     written; that is the duty of the caller.
  8.1045 + * \param temp_callbacks
  8.1046 + *                     A set of callbacks to use for I/O on temp_handle.
  8.1047 + *                     The only mandatory callback is \a write.
  8.1048 + * \assert
  8.1049 + *    \code chain != NULL \endcode
  8.1050 + * \retval FLAC__bool
  8.1051 + *    \c true if the write succeeded, else \c false.  On failure,
  8.1052 + *    check the status with FLAC__metadata_chain_status().
  8.1053 + */
  8.1054 +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks);
  8.1055 +
  8.1056 +/** Merge adjacent PADDING blocks into a single block.
  8.1057 + *
  8.1058 + * \note This function does not write to the FLAC file, it only
  8.1059 + * modifies the chain.
  8.1060 + *
  8.1061 + * \warning Any iterator on the current chain will become invalid after this
  8.1062 + * call.  You should delete the iterator and get a new one.
  8.1063 + *
  8.1064 + * \param chain               A pointer to an existing chain.
  8.1065 + * \assert
  8.1066 + *    \code chain != NULL \endcode
  8.1067 + */
  8.1068 +FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
  8.1069 +
  8.1070 +/** This function will move all PADDING blocks to the end on the metadata,
  8.1071 + *  then merge them into a single block.
  8.1072 + *
  8.1073 + * \note This function does not write to the FLAC file, it only
  8.1074 + * modifies the chain.
  8.1075 + *
  8.1076 + * \warning Any iterator on the current chain will become invalid after this
  8.1077 + * call.  You should delete the iterator and get a new one.
  8.1078 + *
  8.1079 + * \param chain  A pointer to an existing chain.
  8.1080 + * \assert
  8.1081 + *    \code chain != NULL \endcode
  8.1082 + */
  8.1083 +FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
  8.1084 +
  8.1085 +
  8.1086 +/*********** FLAC__Metadata_Iterator ***********/
  8.1087 +
  8.1088 +/** Create a new iterator instance.
  8.1089 + *
  8.1090 + * \retval FLAC__Metadata_Iterator*
  8.1091 + *    \c NULL if there was an error allocating memory, else the new instance.
  8.1092 + */
  8.1093 +FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
  8.1094 +
  8.1095 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  8.1096 + *
  8.1097 + * \param iterator  A pointer to an existing iterator.
  8.1098 + * \assert
  8.1099 + *    \code iterator != NULL \endcode
  8.1100 + */
  8.1101 +FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
  8.1102 +
  8.1103 +/** Initialize the iterator to point to the first metadata block in the
  8.1104 + *  given chain.
  8.1105 + *
  8.1106 + * \param iterator  A pointer to an existing iterator.
  8.1107 + * \param chain     A pointer to an existing and initialized (read) chain.
  8.1108 + * \assert
  8.1109 + *    \code iterator != NULL \endcode
  8.1110 + *    \code chain != NULL \endcode
  8.1111 + */
  8.1112 +FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
  8.1113 +
  8.1114 +/** Moves the iterator forward one metadata block, returning \c false if
  8.1115 + *  already at the end.
  8.1116 + *
  8.1117 + * \param iterator  A pointer to an existing initialized iterator.
  8.1118 + * \assert
  8.1119 + *    \code iterator != NULL \endcode
  8.1120 + *    \a iterator has been successfully initialized with
  8.1121 + *    FLAC__metadata_iterator_init()
  8.1122 + * \retval FLAC__bool
  8.1123 + *    \c false if already at the last metadata block of the chain, else
  8.1124 + *    \c true.
  8.1125 + */
  8.1126 +FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
  8.1127 +
  8.1128 +/** Moves the iterator backward one metadata block, returning \c false if
  8.1129 + *  already at the beginning.
  8.1130 + *
  8.1131 + * \param iterator  A pointer to an existing initialized iterator.
  8.1132 + * \assert
  8.1133 + *    \code iterator != NULL \endcode
  8.1134 + *    \a iterator has been successfully initialized with
  8.1135 + *    FLAC__metadata_iterator_init()
  8.1136 + * \retval FLAC__bool
  8.1137 + *    \c false if already at the first metadata block of the chain, else
  8.1138 + *    \c true.
  8.1139 + */
  8.1140 +FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
  8.1141 +
  8.1142 +/** Get the type of the metadata block at the current position.
  8.1143 + *
  8.1144 + * \param iterator  A pointer to an existing initialized iterator.
  8.1145 + * \assert
  8.1146 + *    \code iterator != NULL \endcode
  8.1147 + *    \a iterator has been successfully initialized with
  8.1148 + *    FLAC__metadata_iterator_init()
  8.1149 + * \retval FLAC__MetadataType
  8.1150 + *    The type of the metadata block at the current iterator position.
  8.1151 + */
  8.1152 +FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
  8.1153 +
  8.1154 +/** Get the metadata block at the current position.  You can modify
  8.1155 + *  the block in place but must write the chain before the changes
  8.1156 + *  are reflected to the FLAC file.  You do not need to call
  8.1157 + *  FLAC__metadata_iterator_set_block() to reflect the changes;
  8.1158 + *  the pointer returned by FLAC__metadata_iterator_get_block()
  8.1159 + *  points directly into the chain.
  8.1160 + *
  8.1161 + * \warning
  8.1162 + * Do not call FLAC__metadata_object_delete() on the returned object;
  8.1163 + * to delete a block use FLAC__metadata_iterator_delete_block().
  8.1164 + *
  8.1165 + * \param iterator  A pointer to an existing initialized iterator.
  8.1166 + * \assert
  8.1167 + *    \code iterator != NULL \endcode
  8.1168 + *    \a iterator has been successfully initialized with
  8.1169 + *    FLAC__metadata_iterator_init()
  8.1170 + * \retval FLAC__StreamMetadata*
  8.1171 + *    The current metadata block.
  8.1172 + */
  8.1173 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
  8.1174 +
  8.1175 +/** Set the metadata block at the current position, replacing the existing
  8.1176 + *  block.  The new block passed in becomes owned by the chain and it will be
  8.1177 + *  deleted when the chain is deleted.
  8.1178 + *
  8.1179 + * \param iterator  A pointer to an existing initialized iterator.
  8.1180 + * \param block     A pointer to a metadata block.
  8.1181 + * \assert
  8.1182 + *    \code iterator != NULL \endcode
  8.1183 + *    \a iterator has been successfully initialized with
  8.1184 + *    FLAC__metadata_iterator_init()
  8.1185 + *    \code block != NULL \endcode
  8.1186 + * \retval FLAC__bool
  8.1187 + *    \c false if the conditions in the above description are not met, or
  8.1188 + *    a memory allocation error occurs, otherwise \c true.
  8.1189 + */
  8.1190 +FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  8.1191 +
  8.1192 +/** Removes the current block from the chain.  If \a replace_with_padding is
  8.1193 + *  \c true, the block will instead be replaced with a padding block of equal
  8.1194 + *  size.  You can not delete the STREAMINFO block.  The iterator will be
  8.1195 + *  left pointing to the block before the one just "deleted", even if
  8.1196 + *  \a replace_with_padding is \c true.
  8.1197 + *
  8.1198 + * \param iterator              A pointer to an existing initialized iterator.
  8.1199 + * \param replace_with_padding  See above.
  8.1200 + * \assert
  8.1201 + *    \code iterator != NULL \endcode
  8.1202 + *    \a iterator has been successfully initialized with
  8.1203 + *    FLAC__metadata_iterator_init()
  8.1204 + * \retval FLAC__bool
  8.1205 + *    \c false if the conditions in the above description are not met,
  8.1206 + *    otherwise \c true.
  8.1207 + */
  8.1208 +FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
  8.1209 +
  8.1210 +/** Insert a new block before the current block.  You cannot insert a block
  8.1211 + *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
  8.1212 + *  as there can be only one, the one that already exists at the head when you
  8.1213 + *  read in a chain.  The chain takes ownership of the new block and it will be
  8.1214 + *  deleted when the chain is deleted.  The iterator will be left pointing to
  8.1215 + *  the new block.
  8.1216 + *
  8.1217 + * \param iterator  A pointer to an existing initialized iterator.
  8.1218 + * \param block     A pointer to a metadata block to insert.
  8.1219 + * \assert
  8.1220 + *    \code iterator != NULL \endcode
  8.1221 + *    \a iterator has been successfully initialized with
  8.1222 + *    FLAC__metadata_iterator_init()
  8.1223 + * \retval FLAC__bool
  8.1224 + *    \c false if the conditions in the above description are not met, or
  8.1225 + *    a memory allocation error occurs, otherwise \c true.
  8.1226 + */
  8.1227 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  8.1228 +
  8.1229 +/** Insert a new block after the current block.  You cannot insert a STREAMINFO
  8.1230 + *  block as there can be only one, the one that already exists at the head when
  8.1231 + *  you read in a chain.  The chain takes ownership of the new block and it will
  8.1232 + *  be deleted when the chain is deleted.  The iterator will be left pointing to
  8.1233 + *  the new block.
  8.1234 + *
  8.1235 + * \param iterator  A pointer to an existing initialized iterator.
  8.1236 + * \param block     A pointer to a metadata block to insert.
  8.1237 + * \assert
  8.1238 + *    \code iterator != NULL \endcode
  8.1239 + *    \a iterator has been successfully initialized with
  8.1240 + *    FLAC__metadata_iterator_init()
  8.1241 + * \retval FLAC__bool
  8.1242 + *    \c false if the conditions in the above description are not met, or
  8.1243 + *    a memory allocation error occurs, otherwise \c true.
  8.1244 + */
  8.1245 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  8.1246 +
  8.1247 +/* \} */
  8.1248 +
  8.1249 +
  8.1250 +/** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
  8.1251 + *  \ingroup flac_metadata
  8.1252 + *
  8.1253 + * \brief
  8.1254 + * This module contains methods for manipulating FLAC metadata objects.
  8.1255 + *
  8.1256 + * Since many are variable length we have to be careful about the memory
  8.1257 + * management.  We decree that all pointers to data in the object are
  8.1258 + * owned by the object and memory-managed by the object.
  8.1259 + *
  8.1260 + * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
  8.1261 + * functions to create all instances.  When using the
  8.1262 + * FLAC__metadata_object_set_*() functions to set pointers to data, set
  8.1263 + * \a copy to \c true to have the function make it's own copy of the data, or
  8.1264 + * to \c false to give the object ownership of your data.  In the latter case
  8.1265 + * your pointer must be freeable by free() and will be free()d when the object
  8.1266 + * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
  8.1267 + * the data pointer to a FLAC__metadata_object_set_*() function as long as
  8.1268 + * the length argument is 0 and the \a copy argument is \c false.
  8.1269 + *
  8.1270 + * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
  8.1271 + * will return \c NULL in the case of a memory allocation error, otherwise a new
  8.1272 + * object.  The FLAC__metadata_object_set_*() functions return \c false in the
  8.1273 + * case of a memory allocation error.
  8.1274 + *
  8.1275 + * We don't have the convenience of C++ here, so note that the library relies
  8.1276 + * on you to keep the types straight.  In other words, if you pass, for
  8.1277 + * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
  8.1278 + * FLAC__metadata_object_application_set_data(), you will get an assertion
  8.1279 + * failure.
  8.1280 + *
  8.1281 + * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
  8.1282 + * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
  8.1283 + * toward the length or stored in the stream, but it can make working with plain
  8.1284 + * comments (those that don't contain embedded-NULs in the value) easier.
  8.1285 + * Entries passed into these functions have trailing NULs added if missing, and
  8.1286 + * returned entries are guaranteed to have a trailing NUL.
  8.1287 + *
  8.1288 + * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
  8.1289 + * comment entry/name/value will first validate that it complies with the Vorbis
  8.1290 + * comment specification and return false if it does not.
  8.1291 + *
  8.1292 + * There is no need to recalculate the length field on metadata blocks you
  8.1293 + * have modified.  They will be calculated automatically before they  are
  8.1294 + * written back to a file.
  8.1295 + *
  8.1296 + * \{
  8.1297 + */
  8.1298 +
  8.1299 +
  8.1300 +/** Create a new metadata object instance of the given type.
  8.1301 + *
  8.1302 + *  The object will be "empty"; i.e. values and data pointers will be \c 0,
  8.1303 + *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
  8.1304 + *  the vendor string set (but zero comments).
  8.1305 + *
  8.1306 + *  Do not pass in a value greater than or equal to
  8.1307 + *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
  8.1308 + *  doing.
  8.1309 + *
  8.1310 + * \param type  Type of object to create
  8.1311 + * \retval FLAC__StreamMetadata*
  8.1312 + *    \c NULL if there was an error allocating memory or the type code is
  8.1313 + *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
  8.1314 + */
  8.1315 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
  8.1316 +
  8.1317 +/** Create a copy of an existing metadata object.
  8.1318 + *
  8.1319 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  8.1320 + *  object is also copied.  The caller takes ownership of the new block and
  8.1321 + *  is responsible for freeing it with FLAC__metadata_object_delete().
  8.1322 + *
  8.1323 + * \param object  Pointer to object to copy.
  8.1324 + * \assert
  8.1325 + *    \code object != NULL \endcode
  8.1326 + * \retval FLAC__StreamMetadata*
  8.1327 + *    \c NULL if there was an error allocating memory, else the new instance.
  8.1328 + */
  8.1329 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
  8.1330 +
  8.1331 +/** Free a metadata object.  Deletes the object pointed to by \a object.
  8.1332 + *
  8.1333 + *  The delete is a "deep" delete, i.e. dynamically allocated data within the
  8.1334 + *  object is also deleted.
  8.1335 + *
  8.1336 + * \param object  A pointer to an existing object.
  8.1337 + * \assert
  8.1338 + *    \code object != NULL \endcode
  8.1339 + */
  8.1340 +FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
  8.1341 +
  8.1342 +/** Compares two metadata objects.
  8.1343 + *
  8.1344 + *  The compare is "deep", i.e. dynamically allocated data within the
  8.1345 + *  object is also compared.
  8.1346 + *
  8.1347 + * \param block1  A pointer to an existing object.
  8.1348 + * \param block2  A pointer to an existing object.
  8.1349 + * \assert
  8.1350 + *    \code block1 != NULL \endcode
  8.1351 + *    \code block2 != NULL \endcode
  8.1352 + * \retval FLAC__bool
  8.1353 + *    \c true if objects are identical, else \c false.
  8.1354 + */
  8.1355 +FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
  8.1356 +
  8.1357 +/** Sets the application data of an APPLICATION block.
  8.1358 + *
  8.1359 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  8.1360 + *  takes ownership of the pointer.  The existing data will be freed if this
  8.1361 + *  function is successful, otherwise the original data will remain if \a copy
  8.1362 + *  is \c true and malloc() fails.
  8.1363 + *
  8.1364 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  8.1365 + *
  8.1366 + * \param object  A pointer to an existing APPLICATION object.
  8.1367 + * \param data    A pointer to the data to set.
  8.1368 + * \param length  The length of \a data in bytes.
  8.1369 + * \param copy    See above.
  8.1370 + * \assert
  8.1371 + *    \code object != NULL \endcode
  8.1372 + *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
  8.1373 + *    \code (data != NULL && length > 0) ||
  8.1374 + * (data == NULL && length == 0 && copy == false) \endcode
  8.1375 + * \retval FLAC__bool
  8.1376 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.1377 + */
  8.1378 +FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
  8.1379 +
  8.1380 +/** Resize the seekpoint array.
  8.1381 + *
  8.1382 + *  If the size shrinks, elements will truncated; if it grows, new placeholder
  8.1383 + *  points will be added to the end.
  8.1384 + *
  8.1385 + * \param object          A pointer to an existing SEEKTABLE object.
  8.1386 + * \param new_num_points  The desired length of the array; may be \c 0.
  8.1387 + * \assert
  8.1388 + *    \code object != NULL \endcode
  8.1389 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1390 + *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
  8.1391 + * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
  8.1392 + * \retval FLAC__bool
  8.1393 + *    \c false if memory allocation error, else \c true.
  8.1394 + */
  8.1395 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
  8.1396 +
  8.1397 +/** Set a seekpoint in a seektable.
  8.1398 + *
  8.1399 + * \param object     A pointer to an existing SEEKTABLE object.
  8.1400 + * \param point_num  Index into seekpoint array to set.
  8.1401 + * \param point      The point to set.
  8.1402 + * \assert
  8.1403 + *    \code object != NULL \endcode
  8.1404 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1405 + *    \code object->data.seek_table.num_points > point_num \endcode
  8.1406 + */
  8.1407 +FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  8.1408 +
  8.1409 +/** Insert a seekpoint into a seektable.
  8.1410 + *
  8.1411 + * \param object     A pointer to an existing SEEKTABLE object.
  8.1412 + * \param point_num  Index into seekpoint array to set.
  8.1413 + * \param point      The point to set.
  8.1414 + * \assert
  8.1415 + *    \code object != NULL \endcode
  8.1416 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1417 + *    \code object->data.seek_table.num_points >= point_num \endcode
  8.1418 + * \retval FLAC__bool
  8.1419 + *    \c false if memory allocation error, else \c true.
  8.1420 + */
  8.1421 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  8.1422 +
  8.1423 +/** Delete a seekpoint from a seektable.
  8.1424 + *
  8.1425 + * \param object     A pointer to an existing SEEKTABLE object.
  8.1426 + * \param point_num  Index into seekpoint array to set.
  8.1427 + * \assert
  8.1428 + *    \code object != NULL \endcode
  8.1429 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1430 + *    \code object->data.seek_table.num_points > point_num \endcode
  8.1431 + * \retval FLAC__bool
  8.1432 + *    \c false if memory allocation error, else \c true.
  8.1433 + */
  8.1434 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
  8.1435 +
  8.1436 +/** Check a seektable to see if it conforms to the FLAC specification.
  8.1437 + *  See the format specification for limits on the contents of the
  8.1438 + *  seektable.
  8.1439 + *
  8.1440 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1441 + * \assert
  8.1442 + *    \code object != NULL \endcode
  8.1443 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1444 + * \retval FLAC__bool
  8.1445 + *    \c false if seek table is illegal, else \c true.
  8.1446 + */
  8.1447 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
  8.1448 +
  8.1449 +/** Append a number of placeholder points to the end of a seek table.
  8.1450 + *
  8.1451 + * \note
  8.1452 + * As with the other ..._seektable_template_... functions, you should
  8.1453 + * call FLAC__metadata_object_seektable_template_sort() when finished
  8.1454 + * to make the seek table legal.
  8.1455 + *
  8.1456 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1457 + * \param num     The number of placeholder points to append.
  8.1458 + * \assert
  8.1459 + *    \code object != NULL \endcode
  8.1460 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1461 + * \retval FLAC__bool
  8.1462 + *    \c false if memory allocation fails, else \c true.
  8.1463 + */
  8.1464 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
  8.1465 +
  8.1466 +/** Append a specific seek point template to the end of a seek table.
  8.1467 + *
  8.1468 + * \note
  8.1469 + * As with the other ..._seektable_template_... functions, you should
  8.1470 + * call FLAC__metadata_object_seektable_template_sort() when finished
  8.1471 + * to make the seek table legal.
  8.1472 + *
  8.1473 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1474 + * \param sample_number  The sample number of the seek point template.
  8.1475 + * \assert
  8.1476 + *    \code object != NULL \endcode
  8.1477 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1478 + * \retval FLAC__bool
  8.1479 + *    \c false if memory allocation fails, else \c true.
  8.1480 + */
  8.1481 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
  8.1482 +
  8.1483 +/** Append specific seek point templates to the end of a seek table.
  8.1484 + *
  8.1485 + * \note
  8.1486 + * As with the other ..._seektable_template_... functions, you should
  8.1487 + * call FLAC__metadata_object_seektable_template_sort() when finished
  8.1488 + * to make the seek table legal.
  8.1489 + *
  8.1490 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1491 + * \param sample_numbers  An array of sample numbers for the seek points.
  8.1492 + * \param num     The number of seek point templates to append.
  8.1493 + * \assert
  8.1494 + *    \code object != NULL \endcode
  8.1495 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1496 + * \retval FLAC__bool
  8.1497 + *    \c false if memory allocation fails, else \c true.
  8.1498 + */
  8.1499 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
  8.1500 +
  8.1501 +/** Append a set of evenly-spaced seek point templates to the end of a
  8.1502 + *  seek table.
  8.1503 + *
  8.1504 + * \note
  8.1505 + * As with the other ..._seektable_template_... functions, you should
  8.1506 + * call FLAC__metadata_object_seektable_template_sort() when finished
  8.1507 + * to make the seek table legal.
  8.1508 + *
  8.1509 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1510 + * \param num     The number of placeholder points to append.
  8.1511 + * \param total_samples  The total number of samples to be encoded;
  8.1512 + *                       the seekpoints will be spaced approximately
  8.1513 + *                       \a total_samples / \a num samples apart.
  8.1514 + * \assert
  8.1515 + *    \code object != NULL \endcode
  8.1516 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1517 + *    \code total_samples > 0 \endcode
  8.1518 + * \retval FLAC__bool
  8.1519 + *    \c false if memory allocation fails, else \c true.
  8.1520 + */
  8.1521 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
  8.1522 +
  8.1523 +/** Append a set of evenly-spaced seek point templates to the end of a
  8.1524 + *  seek table.
  8.1525 + *
  8.1526 + * \note
  8.1527 + * As with the other ..._seektable_template_... functions, you should
  8.1528 + * call FLAC__metadata_object_seektable_template_sort() when finished
  8.1529 + * to make the seek table legal.
  8.1530 + *
  8.1531 + * \param object  A pointer to an existing SEEKTABLE object.
  8.1532 + * \param samples The number of samples apart to space the placeholder
  8.1533 + *                points.  The first point will be at sample \c 0, the
  8.1534 + *                second at sample \a samples, then 2*\a samples, and
  8.1535 + *                so on.  As long as \a samples and \a total_samples
  8.1536 + *                are greater than \c 0, there will always be at least
  8.1537 + *                one seekpoint at sample \c 0.
  8.1538 + * \param total_samples  The total number of samples to be encoded;
  8.1539 + *                       the seekpoints will be spaced
  8.1540 + *                       \a samples samples apart.
  8.1541 + * \assert
  8.1542 + *    \code object != NULL \endcode
  8.1543 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1544 + *    \code samples > 0 \endcode
  8.1545 + *    \code total_samples > 0 \endcode
  8.1546 + * \retval FLAC__bool
  8.1547 + *    \c false if memory allocation fails, else \c true.
  8.1548 + */
  8.1549 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
  8.1550 +
  8.1551 +/** Sort a seek table's seek points according to the format specification,
  8.1552 + *  removing duplicates.
  8.1553 + *
  8.1554 + * \param object   A pointer to a seek table to be sorted.
  8.1555 + * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
  8.1556 + *                 If \c true, duplicates are deleted and the seek table is
  8.1557 + *                 shrunk appropriately; the number of placeholder points
  8.1558 + *                 present in the seek table will be the same after the call
  8.1559 + *                 as before.
  8.1560 + * \assert
  8.1561 + *    \code object != NULL \endcode
  8.1562 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  8.1563 + * \retval FLAC__bool
  8.1564 + *    \c false if realloc() fails, else \c true.
  8.1565 + */
  8.1566 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
  8.1567 +
  8.1568 +/** Sets the vendor string in a VORBIS_COMMENT block.
  8.1569 + *
  8.1570 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
  8.1571 + *  one already.
  8.1572 + *
  8.1573 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  8.1574 + *  takes ownership of the \c entry.entry pointer.
  8.1575 + *
  8.1576 + *  \note If this function returns \c false, the caller still owns the
  8.1577 + *  pointer.
  8.1578 + *
  8.1579 + * \param object  A pointer to an existing VORBIS_COMMENT object.
  8.1580 + * \param entry   The entry to set the vendor string to.
  8.1581 + * \param copy    See above.
  8.1582 + * \assert
  8.1583 + *    \code object != NULL \endcode
  8.1584 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1585 + *    \code (entry.entry != NULL && entry.length > 0) ||
  8.1586 + * (entry.entry == NULL && entry.length == 0) \endcode
  8.1587 + * \retval FLAC__bool
  8.1588 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1589 + *    Vorbis comment specification, else \c true.
  8.1590 + */
  8.1591 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  8.1592 +
  8.1593 +/** Resize the comment array.
  8.1594 + *
  8.1595 + *  If the size shrinks, elements will truncated; if it grows, new empty
  8.1596 + *  fields will be added to the end.
  8.1597 + *
  8.1598 + * \param object            A pointer to an existing VORBIS_COMMENT object.
  8.1599 + * \param new_num_comments  The desired length of the array; may be \c 0.
  8.1600 + * \assert
  8.1601 + *    \code object != NULL \endcode
  8.1602 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1603 + *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
  8.1604 + * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
  8.1605 + * \retval FLAC__bool
  8.1606 + *    \c false if memory allocation fails, else \c true.
  8.1607 + */
  8.1608 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
  8.1609 +
  8.1610 +/** Sets a comment in a VORBIS_COMMENT block.
  8.1611 + *
  8.1612 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
  8.1613 + *  one already.
  8.1614 + *
  8.1615 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  8.1616 + *  takes ownership of the \c entry.entry pointer.
  8.1617 + *
  8.1618 + *  \note If this function returns \c false, the caller still owns the
  8.1619 + *  pointer.
  8.1620 + *
  8.1621 + * \param object       A pointer to an existing VORBIS_COMMENT object.
  8.1622 + * \param comment_num  Index into comment array to set.
  8.1623 + * \param entry        The entry to set the comment to.
  8.1624 + * \param copy         See above.
  8.1625 + * \assert
  8.1626 + *    \code object != NULL \endcode
  8.1627 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1628 + *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
  8.1629 + *    \code (entry.entry != NULL && entry.length > 0) ||
  8.1630 + * (entry.entry == NULL && entry.length == 0) \endcode
  8.1631 + * \retval FLAC__bool
  8.1632 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1633 + *    Vorbis comment specification, else \c true.
  8.1634 + */
  8.1635 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  8.1636 +
  8.1637 +/** Insert a comment in a VORBIS_COMMENT block at the given index.
  8.1638 + *
  8.1639 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
  8.1640 + *  one already.
  8.1641 + *
  8.1642 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  8.1643 + *  takes ownership of the \c entry.entry pointer.
  8.1644 + *
  8.1645 + *  \note If this function returns \c false, the caller still owns the
  8.1646 + *  pointer.
  8.1647 + *
  8.1648 + * \param object       A pointer to an existing VORBIS_COMMENT object.
  8.1649 + * \param comment_num  The index at which to insert the comment.  The comments
  8.1650 + *                     at and after \a comment_num move right one position.
  8.1651 + *                     To append a comment to the end, set \a comment_num to
  8.1652 + *                     \c object->data.vorbis_comment.num_comments .
  8.1653 + * \param entry        The comment to insert.
  8.1654 + * \param copy         See above.
  8.1655 + * \assert
  8.1656 + *    \code object != NULL \endcode
  8.1657 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1658 + *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
  8.1659 + *    \code (entry.entry != NULL && entry.length > 0) ||
  8.1660 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  8.1661 + * \retval FLAC__bool
  8.1662 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1663 + *    Vorbis comment specification, else \c true.
  8.1664 + */
  8.1665 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  8.1666 +
  8.1667 +/** Appends a comment to a VORBIS_COMMENT block.
  8.1668 + *
  8.1669 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
  8.1670 + *  one already.
  8.1671 + *
  8.1672 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  8.1673 + *  takes ownership of the \c entry.entry pointer.
  8.1674 + *
  8.1675 + *  \note If this function returns \c false, the caller still owns the
  8.1676 + *  pointer.
  8.1677 + *
  8.1678 + * \param object       A pointer to an existing VORBIS_COMMENT object.
  8.1679 + * \param entry        The comment to insert.
  8.1680 + * \param copy         See above.
  8.1681 + * \assert
  8.1682 + *    \code object != NULL \endcode
  8.1683 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1684 + *    \code (entry.entry != NULL && entry.length > 0) ||
  8.1685 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  8.1686 + * \retval FLAC__bool
  8.1687 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1688 + *    Vorbis comment specification, else \c true.
  8.1689 + */
  8.1690 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  8.1691 +
  8.1692 +/** Replaces comments in a VORBIS_COMMENT block with a new one.
  8.1693 + *
  8.1694 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
  8.1695 + *  one already.
  8.1696 + *
  8.1697 + *  Depending on the the value of \a all, either all or just the first comment
  8.1698 + *  whose field name(s) match the given entry's name will be replaced by the
  8.1699 + *  given entry.  If no comments match, \a entry will simply be appended.
  8.1700 + *
  8.1701 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  8.1702 + *  takes ownership of the \c entry.entry pointer.
  8.1703 + *
  8.1704 + *  \note If this function returns \c false, the caller still owns the
  8.1705 + *  pointer.
  8.1706 + *
  8.1707 + * \param object       A pointer to an existing VORBIS_COMMENT object.
  8.1708 + * \param entry        The comment to insert.
  8.1709 + * \param all          If \c true, all comments whose field name matches
  8.1710 + *                     \a entry's field name will be removed, and \a entry will
  8.1711 + *                     be inserted at the position of the first matching
  8.1712 + *                     comment.  If \c false, only the first comment whose
  8.1713 + *                     field name matches \a entry's field name will be
  8.1714 + *                     replaced with \a entry.
  8.1715 + * \param copy         See above.
  8.1716 + * \assert
  8.1717 + *    \code object != NULL \endcode
  8.1718 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1719 + *    \code (entry.entry != NULL && entry.length > 0) ||
  8.1720 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  8.1721 + * \retval FLAC__bool
  8.1722 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1723 + *    Vorbis comment specification, else \c true.
  8.1724 + */
  8.1725 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
  8.1726 +
  8.1727 +/** Delete a comment in a VORBIS_COMMENT block at the given index.
  8.1728 + *
  8.1729 + * \param object       A pointer to an existing VORBIS_COMMENT object.
  8.1730 + * \param comment_num  The index of the comment to delete.
  8.1731 + * \assert
  8.1732 + *    \code object != NULL \endcode
  8.1733 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1734 + *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
  8.1735 + * \retval FLAC__bool
  8.1736 + *    \c false if realloc() fails, else \c true.
  8.1737 + */
  8.1738 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
  8.1739 +
  8.1740 +/** Creates a Vorbis comment entry from NUL-terminated name and value strings.
  8.1741 + *
  8.1742 + *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
  8.1743 + *  memory and shall be owned by the caller.  For convenience the entry will
  8.1744 + *  have a terminating NUL.
  8.1745 + *
  8.1746 + * \param entry              A pointer to a Vorbis comment entry.  The entry's
  8.1747 + *                           \c entry pointer should not point to allocated
  8.1748 + *                           memory as it will be overwritten.
  8.1749 + * \param field_name         The field name in ASCII, \c NUL terminated.
  8.1750 + * \param field_value        The field value in UTF-8, \c NUL terminated.
  8.1751 + * \assert
  8.1752 + *    \code entry != NULL \endcode
  8.1753 + *    \code field_name != NULL \endcode
  8.1754 + *    \code field_value != NULL \endcode
  8.1755 + * \retval FLAC__bool
  8.1756 + *    \c false if malloc() fails, or if \a field_name or \a field_value does
  8.1757 + *    not comply with the Vorbis comment specification, else \c true.
  8.1758 + */
  8.1759 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value);
  8.1760 +
  8.1761 +/** Splits a Vorbis comment entry into NUL-terminated name and value strings.
  8.1762 + *
  8.1763 + *  The returned pointers to name and value will be allocated by malloc()
  8.1764 + *  and shall be owned by the caller.
  8.1765 + *
  8.1766 + * \param entry              An existing Vorbis comment entry.
  8.1767 + * \param field_name         The address of where the returned pointer to the
  8.1768 + *                           field name will be stored.
  8.1769 + * \param field_value        The address of where the returned pointer to the
  8.1770 + *                           field value will be stored.
  8.1771 + * \assert
  8.1772 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
  8.1773 + *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
  8.1774 + *    \code field_name != NULL \endcode
  8.1775 + *    \code field_value != NULL \endcode
  8.1776 + * \retval FLAC__bool
  8.1777 + *    \c false if memory allocation fails or \a entry does not comply with the
  8.1778 + *    Vorbis comment specification, else \c true.
  8.1779 + */
  8.1780 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value);
  8.1781 +
  8.1782 +/** Check if the given Vorbis comment entry's field name matches the given
  8.1783 + *  field name.
  8.1784 + *
  8.1785 + * \param entry              An existing Vorbis comment entry.
  8.1786 + * \param field_name         The field name to check.
  8.1787 + * \param field_name_length  The length of \a field_name, not including the
  8.1788 + *                           terminating \c NUL.
  8.1789 + * \assert
  8.1790 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
  8.1791 + * \retval FLAC__bool
  8.1792 + *    \c true if the field names match, else \c false
  8.1793 + */
  8.1794 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
  8.1795 +
  8.1796 +/** Find a Vorbis comment with the given field name.
  8.1797 + *
  8.1798 + *  The search begins at entry number \a offset; use an offset of 0 to
  8.1799 + *  search from the beginning of the comment array.
  8.1800 + *
  8.1801 + * \param object      A pointer to an existing VORBIS_COMMENT object.
  8.1802 + * \param offset      The offset into the comment array from where to start
  8.1803 + *                    the search.
  8.1804 + * \param field_name  The field name of the comment to find.
  8.1805 + * \assert
  8.1806 + *    \code object != NULL \endcode
  8.1807 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1808 + *    \code field_name != NULL \endcode
  8.1809 + * \retval int
  8.1810 + *    The offset in the comment array of the first comment whose field
  8.1811 + *    name matches \a field_name, or \c -1 if no match was found.
  8.1812 + */
  8.1813 +FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
  8.1814 +
  8.1815 +/** Remove first Vorbis comment matching the given field name.
  8.1816 + *
  8.1817 + * \param object      A pointer to an existing VORBIS_COMMENT object.
  8.1818 + * \param field_name  The field name of comment to delete.
  8.1819 + * \assert
  8.1820 + *    \code object != NULL \endcode
  8.1821 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1822 + * \retval int
  8.1823 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
  8.1824 + *    \c 1 for one matching entry deleted.
  8.1825 + */
  8.1826 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
  8.1827 +
  8.1828 +/** Remove all Vorbis comments matching the given field name.
  8.1829 + *
  8.1830 + * \param object      A pointer to an existing VORBIS_COMMENT object.
  8.1831 + * \param field_name  The field name of comments to delete.
  8.1832 + * \assert
  8.1833 + *    \code object != NULL \endcode
  8.1834 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  8.1835 + * \retval int
  8.1836 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
  8.1837 + *    else the number of matching entries deleted.
  8.1838 + */
  8.1839 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
  8.1840 +
  8.1841 +/** Create a new CUESHEET track instance.
  8.1842 + *
  8.1843 + *  The object will be "empty"; i.e. values and data pointers will be \c 0.
  8.1844 + *
  8.1845 + * \retval FLAC__StreamMetadata_CueSheet_Track*
  8.1846 + *    \c NULL if there was an error allocating memory, else the new instance.
  8.1847 + */
  8.1848 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
  8.1849 +
  8.1850 +/** Create a copy of an existing CUESHEET track object.
  8.1851 + *
  8.1852 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  8.1853 + *  object is also copied.  The caller takes ownership of the new object and
  8.1854 + *  is responsible for freeing it with
  8.1855 + *  FLAC__metadata_object_cuesheet_track_delete().
  8.1856 + *
  8.1857 + * \param object  Pointer to object to copy.
  8.1858 + * \assert
  8.1859 + *    \code object != NULL \endcode
  8.1860 + * \retval FLAC__StreamMetadata_CueSheet_Track*
  8.1861 + *    \c NULL if there was an error allocating memory, else the new instance.
  8.1862 + */
  8.1863 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
  8.1864 +
  8.1865 +/** Delete a CUESHEET track object
  8.1866 + *
  8.1867 + * \param object       A pointer to an existing CUESHEET track object.
  8.1868 + * \assert
  8.1869 + *    \code object != NULL \endcode
  8.1870 + */
  8.1871 +FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
  8.1872 +
  8.1873 +/** Resize a track's index point array.
  8.1874 + *
  8.1875 + *  If the size shrinks, elements will truncated; if it grows, new blank
  8.1876 + *  indices will be added to the end.
  8.1877 + *
  8.1878 + * \param object           A pointer to an existing CUESHEET object.
  8.1879 + * \param track_num        The index of the track to modify.  NOTE: this is not
  8.1880 + *                         necessarily the same as the track's \a number field.
  8.1881 + * \param new_num_indices  The desired length of the array; may be \c 0.
  8.1882 + * \assert
  8.1883 + *    \code object != NULL \endcode
  8.1884 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1885 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  8.1886 + *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
  8.1887 + * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
  8.1888 + * \retval FLAC__bool
  8.1889 + *    \c false if memory allocation error, else \c true.
  8.1890 + */
  8.1891 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
  8.1892 +
  8.1893 +/** Insert an index point in a CUESHEET track at the given index.
  8.1894 + *
  8.1895 + * \param object       A pointer to an existing CUESHEET object.
  8.1896 + * \param track_num    The index of the track to modify.  NOTE: this is not
  8.1897 + *                     necessarily the same as the track's \a number field.
  8.1898 + * \param index_num    The index into the track's index array at which to
  8.1899 + *                     insert the index point.  NOTE: this is not necessarily
  8.1900 + *                     the same as the index point's \a number field.  The
  8.1901 + *                     indices at and after \a index_num move right one
  8.1902 + *                     position.  To append an index point to the end, set
  8.1903 + *                     \a index_num to
  8.1904 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  8.1905 + * \param index        The index point to insert.
  8.1906 + * \assert
  8.1907 + *    \code object != NULL \endcode
  8.1908 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1909 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  8.1910 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  8.1911 + * \retval FLAC__bool
  8.1912 + *    \c false if realloc() fails, else \c true.
  8.1913 + */
  8.1914 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index);
  8.1915 +
  8.1916 +/** Insert a blank index point in a CUESHEET track at the given index.
  8.1917 + *
  8.1918 + *  A blank index point is one in which all field values are zero.
  8.1919 + *
  8.1920 + * \param object       A pointer to an existing CUESHEET object.
  8.1921 + * \param track_num    The index of the track to modify.  NOTE: this is not
  8.1922 + *                     necessarily the same as the track's \a number field.
  8.1923 + * \param index_num    The index into the track's index array at which to
  8.1924 + *                     insert the index point.  NOTE: this is not necessarily
  8.1925 + *                     the same as the index point's \a number field.  The
  8.1926 + *                     indices at and after \a index_num move right one
  8.1927 + *                     position.  To append an index point to the end, set
  8.1928 + *                     \a index_num to
  8.1929 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  8.1930 + * \assert
  8.1931 + *    \code object != NULL \endcode
  8.1932 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1933 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  8.1934 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  8.1935 + * \retval FLAC__bool
  8.1936 + *    \c false if realloc() fails, else \c true.
  8.1937 + */
  8.1938 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  8.1939 +
  8.1940 +/** Delete an index point in a CUESHEET track at the given index.
  8.1941 + *
  8.1942 + * \param object       A pointer to an existing CUESHEET object.
  8.1943 + * \param track_num    The index into the track array of the track to
  8.1944 + *                     modify.  NOTE: this is not necessarily the same
  8.1945 + *                     as the track's \a number field.
  8.1946 + * \param index_num    The index into the track's index array of the index
  8.1947 + *                     to delete.  NOTE: this is not necessarily the same
  8.1948 + *                     as the index's \a number field.
  8.1949 + * \assert
  8.1950 + *    \code object != NULL \endcode
  8.1951 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1952 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  8.1953 + *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
  8.1954 + * \retval FLAC__bool
  8.1955 + *    \c false if realloc() fails, else \c true.
  8.1956 + */
  8.1957 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  8.1958 +
  8.1959 +/** Resize the track array.
  8.1960 + *
  8.1961 + *  If the size shrinks, elements will truncated; if it grows, new blank
  8.1962 + *  tracks will be added to the end.
  8.1963 + *
  8.1964 + * \param object            A pointer to an existing CUESHEET object.
  8.1965 + * \param new_num_tracks    The desired length of the array; may be \c 0.
  8.1966 + * \assert
  8.1967 + *    \code object != NULL \endcode
  8.1968 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1969 + *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
  8.1970 + * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
  8.1971 + * \retval FLAC__bool
  8.1972 + *    \c false if memory allocation error, else \c true.
  8.1973 + */
  8.1974 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
  8.1975 +
  8.1976 +/** Sets a track in a CUESHEET block.
  8.1977 + *
  8.1978 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  8.1979 + *  takes ownership of the \a track pointer.
  8.1980 + *
  8.1981 + * \param object       A pointer to an existing CUESHEET object.
  8.1982 + * \param track_num    Index into track array to set.  NOTE: this is not
  8.1983 + *                     necessarily the same as the track's \a number field.
  8.1984 + * \param track        The track to set the track to.  You may safely pass in
  8.1985 + *                     a const pointer if \a copy is \c true.
  8.1986 + * \param copy         See above.
  8.1987 + * \assert
  8.1988 + *    \code object != NULL \endcode
  8.1989 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.1990 + *    \code track_num < object->data.cue_sheet.num_tracks \endcode
  8.1991 + *    \code (track->indices != NULL && track->num_indices > 0) ||
  8.1992 + * (track->indices == NULL && track->num_indices == 0)
  8.1993 + * \retval FLAC__bool
  8.1994 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.1995 + */
  8.1996 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  8.1997 +
  8.1998 +/** Insert a track in a CUESHEET block at the given index.
  8.1999 + *
  8.2000 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  8.2001 + *  takes ownership of the \a track pointer.
  8.2002 + *
  8.2003 + * \param object       A pointer to an existing CUESHEET object.
  8.2004 + * \param track_num    The index at which to insert the track.  NOTE: this
  8.2005 + *                     is not necessarily the same as the track's \a number
  8.2006 + *                     field.  The tracks at and after \a track_num move right
  8.2007 + *                     one position.  To append a track to the end, set
  8.2008 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  8.2009 + * \param track        The track to insert.  You may safely pass in a const
  8.2010 + *                     pointer if \a copy is \c true.
  8.2011 + * \param copy         See above.
  8.2012 + * \assert
  8.2013 + *    \code object != NULL \endcode
  8.2014 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.2015 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  8.2016 + * \retval FLAC__bool
  8.2017 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.2018 + */
  8.2019 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  8.2020 +
  8.2021 +/** Insert a blank track in a CUESHEET block at the given index.
  8.2022 + *
  8.2023 + *  A blank track is one in which all field values are zero.
  8.2024 + *
  8.2025 + * \param object       A pointer to an existing CUESHEET object.
  8.2026 + * \param track_num    The index at which to insert the track.  NOTE: this
  8.2027 + *                     is not necessarily the same as the track's \a number
  8.2028 + *                     field.  The tracks at and after \a track_num move right
  8.2029 + *                     one position.  To append a track to the end, set
  8.2030 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  8.2031 + * \assert
  8.2032 + *    \code object != NULL \endcode
  8.2033 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.2034 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  8.2035 + * \retval FLAC__bool
  8.2036 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.2037 + */
  8.2038 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
  8.2039 +
  8.2040 +/** Delete a track in a CUESHEET block at the given index.
  8.2041 + *
  8.2042 + * \param object       A pointer to an existing CUESHEET object.
  8.2043 + * \param track_num    The index into the track array of the track to
  8.2044 + *                     delete.  NOTE: this is not necessarily the same
  8.2045 + *                     as the track's \a number field.
  8.2046 + * \assert
  8.2047 + *    \code object != NULL \endcode
  8.2048 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.2049 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  8.2050 + * \retval FLAC__bool
  8.2051 + *    \c false if realloc() fails, else \c true.
  8.2052 + */
  8.2053 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
  8.2054 +
  8.2055 +/** Check a cue sheet to see if it conforms to the FLAC specification.
  8.2056 + *  See the format specification for limits on the contents of the
  8.2057 + *  cue sheet.
  8.2058 + *
  8.2059 + * \param object     A pointer to an existing CUESHEET object.
  8.2060 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
  8.2061 + *                   stringent requirements for a CD-DA (audio) disc.
  8.2062 + * \param violation  Address of a pointer to a string.  If there is a
  8.2063 + *                   violation, a pointer to a string explanation of the
  8.2064 + *                   violation will be returned here. \a violation may be
  8.2065 + *                   \c NULL if you don't need the returned string.  Do not
  8.2066 + *                   free the returned string; it will always point to static
  8.2067 + *                   data.
  8.2068 + * \assert
  8.2069 + *    \code object != NULL \endcode
  8.2070 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.2071 + * \retval FLAC__bool
  8.2072 + *    \c false if cue sheet is illegal, else \c true.
  8.2073 + */
  8.2074 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
  8.2075 +
  8.2076 +/** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
  8.2077 + *  assumes the cue sheet corresponds to a CD; the result is undefined
  8.2078 + *  if the cuesheet's is_cd bit is not set.
  8.2079 + *
  8.2080 + * \param object     A pointer to an existing CUESHEET object.
  8.2081 + * \assert
  8.2082 + *    \code object != NULL \endcode
  8.2083 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  8.2084 + * \retval FLAC__uint32
  8.2085 + *    The unsigned integer representation of the CDDB/freedb ID
  8.2086 + */
  8.2087 +FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
  8.2088 +
  8.2089 +/** Sets the MIME type of a PICTURE block.
  8.2090 + *
  8.2091 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  8.2092 + *  takes ownership of the pointer.  The existing string will be freed if this
  8.2093 + *  function is successful, otherwise the original string will remain if \a copy
  8.2094 + *  is \c true and malloc() fails.
  8.2095 + *
  8.2096 + * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
  8.2097 + *
  8.2098 + * \param object      A pointer to an existing PICTURE object.
  8.2099 + * \param mime_type   A pointer to the MIME type string.  The string must be
  8.2100 + *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
  8.2101 + *                    is done.
  8.2102 + * \param copy        See above.
  8.2103 + * \assert
  8.2104 + *    \code object != NULL \endcode
  8.2105 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  8.2106 + *    \code (mime_type != NULL) \endcode
  8.2107 + * \retval FLAC__bool
  8.2108 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.2109 + */
  8.2110 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
  8.2111 +
  8.2112 +/** Sets the description of a PICTURE block.
  8.2113 + *
  8.2114 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  8.2115 + *  takes ownership of the pointer.  The existing string will be freed if this
  8.2116 + *  function is successful, otherwise the original string will remain if \a copy
  8.2117 + *  is \c true and malloc() fails.
  8.2118 + *
  8.2119 + * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
  8.2120 + *
  8.2121 + * \param object      A pointer to an existing PICTURE object.
  8.2122 + * \param description A pointer to the description string.  The string must be
  8.2123 + *                    valid UTF-8, NUL-terminated.  No validation is done.
  8.2124 + * \param copy        See above.
  8.2125 + * \assert
  8.2126 + *    \code object != NULL \endcode
  8.2127 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  8.2128 + *    \code (description != NULL) \endcode
  8.2129 + * \retval FLAC__bool
  8.2130 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.2131 + */
  8.2132 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
  8.2133 +
  8.2134 +/** Sets the picture data of a PICTURE block.
  8.2135 + *
  8.2136 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  8.2137 + *  takes ownership of the pointer.  Also sets the \a data_length field of the
  8.2138 + *  metadata object to what is passed in as the \a length parameter.  The
  8.2139 + *  existing data will be freed if this function is successful, otherwise the
  8.2140 + *  original data and data_length will remain if \a copy is \c true and
  8.2141 + *  malloc() fails.
  8.2142 + *
  8.2143 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  8.2144 + *
  8.2145 + * \param object  A pointer to an existing PICTURE object.
  8.2146 + * \param data    A pointer to the data to set.
  8.2147 + * \param length  The length of \a data in bytes.
  8.2148 + * \param copy    See above.
  8.2149 + * \assert
  8.2150 + *    \code object != NULL \endcode
  8.2151 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  8.2152 + *    \code (data != NULL && length > 0) ||
  8.2153 + * (data == NULL && length == 0 && copy == false) \endcode
  8.2154 + * \retval FLAC__bool
  8.2155 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
  8.2156 + */
  8.2157 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
  8.2158 +
  8.2159 +/** Check a PICTURE block to see if it conforms to the FLAC specification.
  8.2160 + *  See the format specification for limits on the contents of the
  8.2161 + *  PICTURE block.
  8.2162 + *
  8.2163 + * \param object     A pointer to existing PICTURE block to be checked.
  8.2164 + * \param violation  Address of a pointer to a string.  If there is a
  8.2165 + *                   violation, a pointer to a string explanation of the
  8.2166 + *                   violation will be returned here. \a violation may be
  8.2167 + *                   \c NULL if you don't need the returned string.  Do not
  8.2168 + *                   free the returned string; it will always point to static
  8.2169 + *                   data.
  8.2170 + * \assert
  8.2171 + *    \code object != NULL \endcode
  8.2172 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  8.2173 + * \retval FLAC__bool
  8.2174 + *    \c false if PICTURE block is illegal, else \c true.
  8.2175 + */
  8.2176 +FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
  8.2177 +
  8.2178 +/* \} */
  8.2179 +
  8.2180 +#ifdef __cplusplus
  8.2181 +}
  8.2182 +#endif
  8.2183 +
  8.2184 +#endif
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/VisualC/external/include/FLAC/ordinals.h	Mon Jan 09 04:20:54 2012 -0500
     9.3 @@ -0,0 +1,80 @@
     9.4 +/* libFLAC - Free Lossless Audio Codec library
     9.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     9.6 + *
     9.7 + * Redistribution and use in source and binary forms, with or without
     9.8 + * modification, are permitted provided that the following conditions
     9.9 + * are met:
    9.10 + *
    9.11 + * - Redistributions of source code must retain the above copyright
    9.12 + * notice, this list of conditions and the following disclaimer.
    9.13 + *
    9.14 + * - Redistributions in binary form must reproduce the above copyright
    9.15 + * notice, this list of conditions and the following disclaimer in the
    9.16 + * documentation and/or other materials provided with the distribution.
    9.17 + *
    9.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    9.19 + * contributors may be used to endorse or promote products derived from
    9.20 + * this software without specific prior written permission.
    9.21 + *
    9.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    9.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    9.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    9.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    9.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    9.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    9.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    9.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    9.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    9.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    9.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    9.33 + */
    9.34 +
    9.35 +#ifndef FLAC__ORDINALS_H
    9.36 +#define FLAC__ORDINALS_H
    9.37 +
    9.38 +#if !(defined(_MSC_VER) || defined(__BORLANDC__) || defined(__EMX__))
    9.39 +#include <inttypes.h>
    9.40 +#endif
    9.41 +
    9.42 +typedef signed char FLAC__int8;
    9.43 +typedef unsigned char FLAC__uint8;
    9.44 +
    9.45 +#if defined(_MSC_VER) || defined(__BORLANDC__)
    9.46 +typedef __int16 FLAC__int16;
    9.47 +typedef __int32 FLAC__int32;
    9.48 +typedef __int64 FLAC__int64;
    9.49 +typedef unsigned __int16 FLAC__uint16;
    9.50 +typedef unsigned __int32 FLAC__uint32;
    9.51 +typedef unsigned __int64 FLAC__uint64;
    9.52 +#elif defined(__EMX__)
    9.53 +typedef short FLAC__int16;
    9.54 +typedef long FLAC__int32;
    9.55 +typedef long long FLAC__int64;
    9.56 +typedef unsigned short FLAC__uint16;
    9.57 +typedef unsigned long FLAC__uint32;
    9.58 +typedef unsigned long long FLAC__uint64;
    9.59 +#else
    9.60 +typedef int16_t FLAC__int16;
    9.61 +typedef int32_t FLAC__int32;
    9.62 +typedef int64_t FLAC__int64;
    9.63 +typedef uint16_t FLAC__uint16;
    9.64 +typedef uint32_t FLAC__uint32;
    9.65 +typedef uint64_t FLAC__uint64;
    9.66 +#endif
    9.67 +
    9.68 +typedef int FLAC__bool;
    9.69 +
    9.70 +typedef FLAC__uint8 FLAC__byte;
    9.71 +
    9.72 +#ifdef true
    9.73 +#undef true
    9.74 +#endif
    9.75 +#ifdef false
    9.76 +#undef false
    9.77 +#endif
    9.78 +#ifndef __cplusplus
    9.79 +#define true 1
    9.80 +#define false 0
    9.81 +#endif
    9.82 +
    9.83 +#endif
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/VisualC/external/include/FLAC/stream_decoder.h	Mon Jan 09 04:20:54 2012 -0500
    10.3 @@ -0,0 +1,1559 @@
    10.4 +/* libFLAC - Free Lossless Audio Codec library
    10.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    10.6 + *
    10.7 + * Redistribution and use in source and binary forms, with or without
    10.8 + * modification, are permitted provided that the following conditions
    10.9 + * are met:
   10.10 + *
   10.11 + * - Redistributions of source code must retain the above copyright
   10.12 + * notice, this list of conditions and the following disclaimer.
   10.13 + *
   10.14 + * - Redistributions in binary form must reproduce the above copyright
   10.15 + * notice, this list of conditions and the following disclaimer in the
   10.16 + * documentation and/or other materials provided with the distribution.
   10.17 + *
   10.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   10.19 + * contributors may be used to endorse or promote products derived from
   10.20 + * this software without specific prior written permission.
   10.21 + *
   10.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   10.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   10.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   10.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   10.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   10.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   10.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   10.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   10.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   10.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   10.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   10.33 + */
   10.34 +
   10.35 +#ifndef FLAC__STREAM_DECODER_H
   10.36 +#define FLAC__STREAM_DECODER_H
   10.37 +
   10.38 +#include <stdio.h> /* for FILE */
   10.39 +#include "export.h"
   10.40 +#include "format.h"
   10.41 +
   10.42 +#ifdef __cplusplus
   10.43 +extern "C" {
   10.44 +#endif
   10.45 +
   10.46 +
   10.47 +/** \file include/FLAC/stream_decoder.h
   10.48 + *
   10.49 + *  \brief
   10.50 + *  This module contains the functions which implement the stream
   10.51 + *  decoder.
   10.52 + *
   10.53 + *  See the detailed documentation in the
   10.54 + *  \link flac_stream_decoder stream decoder \endlink module.
   10.55 + */
   10.56 +
   10.57 +/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
   10.58 + *  \ingroup flac
   10.59 + *
   10.60 + *  \brief
   10.61 + *  This module describes the decoder layers provided by libFLAC.
   10.62 + *
   10.63 + * The stream decoder can be used to decode complete streams either from
   10.64 + * the client via callbacks, or directly from a file, depending on how
   10.65 + * it is initialized.  When decoding via callbacks, the client provides
   10.66 + * callbacks for reading FLAC data and writing decoded samples, and
   10.67 + * handling metadata and errors.  If the client also supplies seek-related
   10.68 + * callback, the decoder function for sample-accurate seeking within the
   10.69 + * FLAC input is also available.  When decoding from a file, the client
   10.70 + * needs only supply a filename or open \c FILE* and write/metadata/error
   10.71 + * callbacks; the rest of the callbacks are supplied internally.  For more
   10.72 + * info see the \link flac_stream_decoder stream decoder \endlink module.
   10.73 + */
   10.74 +
   10.75 +/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
   10.76 + *  \ingroup flac_decoder
   10.77 + *
   10.78 + *  \brief
   10.79 + *  This module contains the functions which implement the stream
   10.80 + *  decoder.
   10.81 + *
   10.82 + * The stream decoder can decode native FLAC, and optionally Ogg FLAC
   10.83 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   10.84 + *
   10.85 + * The basic usage of this decoder is as follows:
   10.86 + * - The program creates an instance of a decoder using
   10.87 + *   FLAC__stream_decoder_new().
   10.88 + * - The program overrides the default settings using
   10.89 + *   FLAC__stream_decoder_set_*() functions.
   10.90 + * - The program initializes the instance to validate the settings and
   10.91 + *   prepare for decoding using
   10.92 + *   - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
   10.93 + *     or FLAC__stream_decoder_init_file() for native FLAC,
   10.94 + *   - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
   10.95 + *     or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
   10.96 + * - The program calls the FLAC__stream_decoder_process_*() functions
   10.97 + *   to decode data, which subsequently calls the callbacks.
   10.98 + * - The program finishes the decoding with FLAC__stream_decoder_finish(),
   10.99 + *   which flushes the input and output and resets the decoder to the
  10.100 + *   uninitialized state.
  10.101 + * - The instance may be used again or deleted with
  10.102 + *   FLAC__stream_decoder_delete().
  10.103 + *
  10.104 + * In more detail, the program will create a new instance by calling
  10.105 + * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
  10.106 + * functions to override the default decoder options, and call
  10.107 + * one of the FLAC__stream_decoder_init_*() functions.
  10.108 + *
  10.109 + * There are three initialization functions for native FLAC, one for
  10.110 + * setting up the decoder to decode FLAC data from the client via
  10.111 + * callbacks, and two for decoding directly from a FLAC file.
  10.112 + *
  10.113 + * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
  10.114 + * You must also supply several callbacks for handling I/O.  Some (like
  10.115 + * seeking) are optional, depending on the capabilities of the input.
  10.116 + *
  10.117 + * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
  10.118 + * or FLAC__stream_decoder_init_file().  Then you must only supply an open
  10.119 + * \c FILE* or filename and fewer callbacks; the decoder will handle
  10.120 + * the other callbacks internally.
  10.121 + *
  10.122 + * There are three similarly-named init functions for decoding from Ogg
  10.123 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  10.124 + * library has been built with Ogg support.
  10.125 + *
  10.126 + * Once the decoder is initialized, your program will call one of several
  10.127 + * functions to start the decoding process:
  10.128 + *
  10.129 + * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
  10.130 + *   most one metadata block or audio frame and return, calling either the
  10.131 + *   metadata callback or write callback, respectively, once.  If the decoder
  10.132 + *   loses sync it will return with only the error callback being called.
  10.133 + * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
  10.134 + *   to process the stream from the current location and stop upon reaching
  10.135 + *   the first audio frame.  The client will get one metadata, write, or error
  10.136 + *   callback per metadata block, audio frame, or sync error, respectively.
  10.137 + * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
  10.138 + *   to process the stream from the current location until the read callback
  10.139 + *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
  10.140 + *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The client will get one metadata,
  10.141 + *   write, or error callback per metadata block, audio frame, or sync error,
  10.142 + *   respectively.
  10.143 + *
  10.144 + * When the decoder has finished decoding (normally or through an abort),
  10.145 + * the instance is finished by calling FLAC__stream_decoder_finish(), which
  10.146 + * ensures the decoder is in the correct state and frees memory.  Then the
  10.147 + * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  10.148 + * again to decode another stream.
  10.149 + *
  10.150 + * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
  10.151 + * At any point after the stream decoder has been initialized, the client can
  10.152 + * call this function to seek to an exact sample within the stream.
  10.153 + * Subsequently, the first time the write callback is called it will be
  10.154 + * passed a (possibly partial) block starting at that sample.
  10.155 + *
  10.156 + * If the client cannot seek via the callback interface provided, but still
  10.157 + * has another way of seeking, it can flush the decoder using
  10.158 + * FLAC__stream_decoder_flush() and start feeding data from the new position
  10.159 + * through the read callback.
  10.160 + *
  10.161 + * The stream decoder also provides MD5 signature checking.  If this is
  10.162 + * turned on before initialization, FLAC__stream_decoder_finish() will
  10.163 + * report when the decoded MD5 signature does not match the one stored
  10.164 + * in the STREAMINFO block.  MD5 checking is automatically turned off
  10.165 + * (until the next FLAC__stream_decoder_reset()) if there is no signature
  10.166 + * in the STREAMINFO block or when a seek is attempted.
  10.167 + *
  10.168 + * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  10.169 + * attention.  By default, the decoder only calls the metadata_callback for
  10.170 + * the STREAMINFO block.  These functions allow you to tell the decoder
  10.171 + * explicitly which blocks to parse and return via the metadata_callback
  10.172 + * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
  10.173 + * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
  10.174 + * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
  10.175 + * which blocks to return.  Remember that metadata blocks can potentially
  10.176 + * be big (for example, cover art) so filtering out the ones you don't
  10.177 + * use can reduce the memory requirements of the decoder.  Also note the
  10.178 + * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
  10.179 + * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
  10.180 + * filtering APPLICATION blocks based on the application ID.
  10.181 + *
  10.182 + * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  10.183 + * they still can legally be filtered from the metadata_callback.
  10.184 + *
  10.185 + * \note
  10.186 + * The "set" functions may only be called when the decoder is in the
  10.187 + * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
  10.188 + * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
  10.189 + * before FLAC__stream_decoder_init_*().  If this is the case they will
  10.190 + * return \c true, otherwise \c false.
  10.191 + *
  10.192 + * \note
  10.193 + * FLAC__stream_decoder_finish() resets all settings to the constructor
  10.194 + * defaults, including the callbacks.
  10.195 + *
  10.196 + * \{
  10.197 + */
  10.198 +
  10.199 +
  10.200 +/** State values for a FLAC__StreamDecoder
  10.201 + *
  10.202 + * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  10.203 + */
  10.204 +typedef enum {
  10.205 +
  10.206 +	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
  10.207 +	/**< The decoder is ready to search for metadata. */
  10.208 +
  10.209 +	FLAC__STREAM_DECODER_READ_METADATA,
  10.210 +	/**< The decoder is ready to or is in the process of reading metadata. */
  10.211 +
  10.212 +	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
  10.213 +	/**< The decoder is ready to or is in the process of searching for the
  10.214 +	 * frame sync code.
  10.215 +	 */
  10.216 +
  10.217 +	FLAC__STREAM_DECODER_READ_FRAME,
  10.218 +	/**< The decoder is ready to or is in the process of reading a frame. */
  10.219 +
  10.220 +	FLAC__STREAM_DECODER_END_OF_STREAM,
  10.221 +	/**< The decoder has reached the end of the stream. */
  10.222 +
  10.223 +	FLAC__STREAM_DECODER_OGG_ERROR,
  10.224 +	/**< An error occurred in the underlying Ogg layer.  */
  10.225 +
  10.226 +	FLAC__STREAM_DECODER_SEEK_ERROR,
  10.227 +	/**< An error occurred while seeking.  The decoder must be flushed
  10.228 +	 * with FLAC__stream_decoder_flush() or reset with
  10.229 +	 * FLAC__stream_decoder_reset() before decoding can continue.
  10.230 +	 */
  10.231 +
  10.232 +	FLAC__STREAM_DECODER_ABORTED,
  10.233 +	/**< The decoder was aborted by the read callback. */
  10.234 +
  10.235 +	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  10.236 +	/**< An error occurred allocating memory.  The decoder is in an invalid
  10.237 +	 * state and can no longer be used.
  10.238 +	 */
  10.239 +
  10.240 +	FLAC__STREAM_DECODER_UNINITIALIZED
  10.241 +	/**< The decoder is in the uninitialized state; one of the
  10.242 +	 * FLAC__stream_decoder_init_*() functions must be called before samples
  10.243 +	 * can be processed.
  10.244 +	 */
  10.245 +
  10.246 +} FLAC__StreamDecoderState;
  10.247 +
  10.248 +/** Maps a FLAC__StreamDecoderState to a C string.
  10.249 + *
  10.250 + *  Using a FLAC__StreamDecoderState as the index to this array
  10.251 + *  will give the string equivalent.  The contents should not be modified.
  10.252 + */
  10.253 +extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
  10.254 +
  10.255 +
  10.256 +/** Possible return values for the FLAC__stream_decoder_init_*() functions.
  10.257 + */
  10.258 +typedef enum {
  10.259 +
  10.260 +	FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
  10.261 +	/**< Initialization was successful. */
  10.262 +
  10.263 +	FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  10.264 +	/**< The library was not compiled with support for the given container
  10.265 +	 * format.
  10.266 +	 */
  10.267 +
  10.268 +	FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
  10.269 +	/**< A required callback was not supplied. */
  10.270 +
  10.271 +	FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
  10.272 +	/**< An error occurred allocating memory. */
  10.273 +
  10.274 +	FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
  10.275 +	/**< fopen() failed in FLAC__stream_decoder_init_file() or
  10.276 +	 * FLAC__stream_decoder_init_ogg_file(). */
  10.277 +
  10.278 +	FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
  10.279 +	/**< FLAC__stream_decoder_init_*() was called when the decoder was
  10.280 +	 * already initialized, usually because
  10.281 +	 * FLAC__stream_decoder_finish() was not called.
  10.282 +	 */
  10.283 +
  10.284 +} FLAC__StreamDecoderInitStatus;
  10.285 +
  10.286 +/** Maps a FLAC__StreamDecoderInitStatus to a C string.
  10.287 + *
  10.288 + *  Using a FLAC__StreamDecoderInitStatus as the index to this array
  10.289 + *  will give the string equivalent.  The contents should not be modified.
  10.290 + */
  10.291 +extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
  10.292 +
  10.293 +
  10.294 +/** Return values for the FLAC__StreamDecoder read callback.
  10.295 + */
  10.296 +typedef enum {
  10.297 +
  10.298 +	FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
  10.299 +	/**< The read was OK and decoding can continue. */
  10.300 +
  10.301 +	FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
  10.302 +	/**< The read was attempted while at the end of the stream.  Note that
  10.303 +	 * the client must only return this value when the read callback was
  10.304 +	 * called when already at the end of the stream.  Otherwise, if the read
  10.305 +	 * itself moves to the end of the stream, the client should still return
  10.306 +	 * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
  10.307 +	 * the next read callback it should return
  10.308 +	 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
  10.309 +	 * of \c 0.
  10.310 +	 */
  10.311 +
  10.312 +	FLAC__STREAM_DECODER_READ_STATUS_ABORT
  10.313 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  10.314 +
  10.315 +} FLAC__StreamDecoderReadStatus;
  10.316 +
  10.317 +/** Maps a FLAC__StreamDecoderReadStatus to a C string.
  10.318 + *
  10.319 + *  Using a FLAC__StreamDecoderReadStatus as the index to this array
  10.320 + *  will give the string equivalent.  The contents should not be modified.
  10.321 + */
  10.322 +extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
  10.323 +
  10.324 +
  10.325 +/** Return values for the FLAC__StreamDecoder seek callback.
  10.326 + */
  10.327 +typedef enum {
  10.328 +
  10.329 +	FLAC__STREAM_DECODER_SEEK_STATUS_OK,
  10.330 +	/**< The seek was OK and decoding can continue. */
  10.331 +
  10.332 +	FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
  10.333 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  10.334 +
  10.335 +	FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  10.336 +	/**< Client does not support seeking. */
  10.337 +
  10.338 +} FLAC__StreamDecoderSeekStatus;
  10.339 +
  10.340 +/** Maps a FLAC__StreamDecoderSeekStatus to a C string.
  10.341 + *
  10.342 + *  Using a FLAC__StreamDecoderSeekStatus as the index to this array
  10.343 + *  will give the string equivalent.  The contents should not be modified.
  10.344 + */
  10.345 +extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
  10.346 +
  10.347 +
  10.348 +/** Return values for the FLAC__StreamDecoder tell callback.
  10.349 + */
  10.350 +typedef enum {
  10.351 +
  10.352 +	FLAC__STREAM_DECODER_TELL_STATUS_OK,
  10.353 +	/**< The tell was OK and decoding can continue. */
  10.354 +
  10.355 +	FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
  10.356 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  10.357 +
  10.358 +	FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  10.359 +	/**< Client does not support telling the position. */
  10.360 +
  10.361 +} FLAC__StreamDecoderTellStatus;
  10.362 +
  10.363 +/** Maps a FLAC__StreamDecoderTellStatus to a C string.
  10.364 + *
  10.365 + *  Using a FLAC__StreamDecoderTellStatus as the index to this array
  10.366 + *  will give the string equivalent.  The contents should not be modified.
  10.367 + */
  10.368 +extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
  10.369 +
  10.370 +
  10.371 +/** Return values for the FLAC__StreamDecoder length callback.
  10.372 + */
  10.373 +typedef enum {
  10.374 +
  10.375 +	FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
  10.376 +	/**< The length call was OK and decoding can continue. */
  10.377 +
  10.378 +	FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
  10.379 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  10.380 +
  10.381 +	FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  10.382 +	/**< Client does not support reporting the length. */
  10.383 +
  10.384 +} FLAC__StreamDecoderLengthStatus;
  10.385 +
  10.386 +/** Maps a FLAC__StreamDecoderLengthStatus to a C string.
  10.387 + *
  10.388 + *  Using a FLAC__StreamDecoderLengthStatus as the index to this array
  10.389 + *  will give the string equivalent.  The contents should not be modified.
  10.390 + */
  10.391 +extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
  10.392 +
  10.393 +
  10.394 +/** Return values for the FLAC__StreamDecoder write callback.
  10.395 + */
  10.396 +typedef enum {
  10.397 +
  10.398 +	FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
  10.399 +	/**< The write was OK and decoding can continue. */
  10.400 +
  10.401 +	FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
  10.402 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  10.403 +
  10.404 +} FLAC__StreamDecoderWriteStatus;
  10.405 +
  10.406 +/** Maps a FLAC__StreamDecoderWriteStatus to a C string.
  10.407 + *
  10.408 + *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
  10.409 + *  will give the string equivalent.  The contents should not be modified.
  10.410 + */
  10.411 +extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
  10.412 +
  10.413 +
  10.414 +/** Possible values passed back to the FLAC__StreamDecoder error callback.
  10.415 + *  \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
  10.416 + *  all.  The rest could be caused by bad sync (false synchronization on
  10.417 + *  data that is not the start of a frame) or corrupted data.  The error
  10.418 + *  itself is the decoder's best guess at what happened assuming a correct
  10.419 + *  sync.  For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
  10.420 + *  could be caused by a correct sync on the start of a frame, but some
  10.421 + *  data in the frame header was corrupted.  Or it could be the result of
  10.422 + *  syncing on a point the stream that looked like the starting of a frame
  10.423 + *  but was not.  \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  10.424 + *  could be because the decoder encountered a valid frame made by a future
  10.425 + *  version of the encoder which it cannot parse, or because of a false
  10.426 + *  sync making it appear as though an encountered frame was generated by
  10.427 + *  a future encoder.
  10.428 + */
  10.429 +typedef enum {
  10.430 +
  10.431 +	FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
  10.432 +	/**< An error in the stream caused the decoder to lose synchronization. */
  10.433 +
  10.434 +	FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
  10.435 +	/**< The decoder encountered a corrupted frame header. */
  10.436 +
  10.437 +	FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
  10.438 +	/**< The frame's data did not match the CRC in the footer. */
  10.439 +
  10.440 +	FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  10.441 +	/**< The decoder encountered reserved fields in use in the stream. */
  10.442 +
  10.443 +} FLAC__StreamDecoderErrorStatus;
  10.444 +
  10.445 +/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
  10.446 + *
  10.447 + *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
  10.448 + *  will give the string equivalent.  The contents should not be modified.
  10.449 + */
  10.450 +extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
  10.451 +
  10.452 +
  10.453 +/***********************************************************************
  10.454 + *
  10.455 + * class FLAC__StreamDecoder
  10.456 + *
  10.457 + ***********************************************************************/
  10.458 +
  10.459 +struct FLAC__StreamDecoderProtected;
  10.460 +struct FLAC__StreamDecoderPrivate;
  10.461 +/** The opaque structure definition for the stream decoder type.
  10.462 + *  See the \link flac_stream_decoder stream decoder module \endlink
  10.463 + *  for a detailed description.
  10.464 + */
  10.465 +typedef struct {
  10.466 +	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  10.467 +	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  10.468 +} FLAC__StreamDecoder;
  10.469 +
  10.470 +/** Signature for the read callback.
  10.471 + *
  10.472 + *  A function pointer matching this signature must be passed to
  10.473 + *  FLAC__stream_decoder_init*_stream(). The supplied function will be
  10.474 + *  called when the decoder needs more input data.  The address of the
  10.475 + *  buffer to be filled is supplied, along with the number of bytes the
  10.476 + *  buffer can hold.  The callback may choose to supply less data and
  10.477 + *  modify the byte count but must be careful not to overflow the buffer.
  10.478 + *  The callback then returns a status code chosen from
  10.479 + *  FLAC__StreamDecoderReadStatus.
  10.480 + *
  10.481 + * Here is an example of a read callback for stdio streams:
  10.482 + * \code
  10.483 + * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  10.484 + * {
  10.485 + *   FILE *file = ((MyClientData*)client_data)->file;
  10.486 + *   if(*bytes > 0) {
  10.487 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  10.488 + *     if(ferror(file))
  10.489 + *       return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  10.490 + *     else if(*bytes == 0)
  10.491 + *       return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
  10.492 + *     else
  10.493 + *       return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
  10.494 + *   }
  10.495 + *   else
  10.496 + *     return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  10.497 + * }
  10.498 + * \endcode
  10.499 + *
  10.500 + * \note In general, FLAC__StreamDecoder functions which change the
  10.501 + * state should not be called on the \a decoder while in the callback.
  10.502 + *
  10.503 + * \param  decoder  The decoder instance calling the callback.
  10.504 + * \param  buffer   A pointer to a location for the callee to store
  10.505 + *                  data to be decoded.
  10.506 + * \param  bytes    A pointer to the size of the buffer.  On entry
  10.507 + *                  to the callback, it contains the maximum number
  10.508 + *                  of bytes that may be stored in \a buffer.  The
  10.509 + *                  callee must set it to the actual number of bytes
  10.510 + *                  stored (0 in case of error or end-of-stream) before
  10.511 + *                  returning.
  10.512 + * \param  client_data  The callee's client data set through
  10.513 + *                      FLAC__stream_decoder_init_*().
  10.514 + * \retval FLAC__StreamDecoderReadStatus
  10.515 + *    The callee's return status.  Note that the callback should return
  10.516 + *    \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
  10.517 + *    zero bytes were read and there is no more data to be read.
  10.518 + */
  10.519 +typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  10.520 +
  10.521 +/** Signature for the seek callback.
  10.522 + *
  10.523 + *  A function pointer matching this signature may be passed to
  10.524 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  10.525 + *  called when the decoder needs to seek the input stream.  The decoder
  10.526 + *  will pass the absolute byte offset to seek to, 0 meaning the
  10.527 + *  beginning of the stream.
  10.528 + *
  10.529 + * Here is an example of a seek callback for stdio streams:
  10.530 + * \code
  10.531 + * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  10.532 + * {
  10.533 + *   FILE *file = ((MyClientData*)client_data)->file;
  10.534 + *   if(file == stdin)
  10.535 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
  10.536 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  10.537 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
  10.538 + *   else
  10.539 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
  10.540 + * }
  10.541 + * \endcode
  10.542 + *
  10.543 + * \note In general, FLAC__StreamDecoder functions which change the
  10.544 + * state should not be called on the \a decoder while in the callback.
  10.545 + *
  10.546 + * \param  decoder  The decoder instance calling the callback.
  10.547 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  10.548 + *                               to seek to.
  10.549 + * \param  client_data  The callee's client data set through
  10.550 + *                      FLAC__stream_decoder_init_*().
  10.551 + * \retval FLAC__StreamDecoderSeekStatus
  10.552 + *    The callee's return status.
  10.553 + */
  10.554 +typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  10.555 +
  10.556 +/** Signature for the tell callback.
  10.557 + *
  10.558 + *  A function pointer matching this signature may be passed to
  10.559 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  10.560 + *  called when the decoder wants to know the current position of the
  10.561 + *  stream.  The callback should return the byte offset from the
  10.562 + *  beginning of the stream.
  10.563 + *
  10.564 + * Here is an example of a tell callback for stdio streams:
  10.565 + * \code
  10.566 + * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  10.567 + * {
  10.568 + *   FILE *file = ((MyClientData*)client_data)->file;
  10.569 + *   off_t pos;
  10.570 + *   if(file == stdin)
  10.571 + *     return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
  10.572 + *   else if((pos = ftello(file)) < 0)
  10.573 + *     return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
  10.574 + *   else {
  10.575 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  10.576 + *     return FLAC__STREAM_DECODER_TELL_STATUS_OK;
  10.577 + *   }
  10.578 + * }
  10.579 + * \endcode
  10.580 + *
  10.581 + * \note In general, FLAC__StreamDecoder functions which change the
  10.582 + * state should not be called on the \a decoder while in the callback.
  10.583 + *
  10.584 + * \param  decoder  The decoder instance calling the callback.
  10.585 + * \param  absolute_byte_offset  A pointer to storage for the current offset
  10.586 + *                               from the beginning of the stream.
  10.587 + * \param  client_data  The callee's client data set through
  10.588 + *                      FLAC__stream_decoder_init_*().
  10.589 + * \retval FLAC__StreamDecoderTellStatus
  10.590 + *    The callee's return status.
  10.591 + */
  10.592 +typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  10.593 +
  10.594 +/** Signature for the length callback.
  10.595 + *
  10.596 + *  A function pointer matching this signature may be passed to
  10.597 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  10.598 + *  called when the decoder wants to know the total length of the stream
  10.599 + *  in bytes.
  10.600 + *
  10.601 + * Here is an example of a length callback for stdio streams:
  10.602 + * \code
  10.603 + * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
  10.604 + * {
  10.605 + *   FILE *file = ((MyClientData*)client_data)->file;
  10.606 + *   struct stat filestats;
  10.607 + *
  10.608 + *   if(file == stdin)
  10.609 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
  10.610 + *   else if(fstat(fileno(file), &filestats) != 0)
  10.611 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
  10.612 + *   else {
  10.613 + *     *stream_length = (FLAC__uint64)filestats.st_size;
  10.614 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
  10.615 + *   }
  10.616 + * }
  10.617 + * \endcode
  10.618 + *
  10.619 + * \note In general, FLAC__StreamDecoder functions which change the
  10.620 + * state should not be called on the \a decoder while in the callback.
  10.621 + *
  10.622 + * \param  decoder  The decoder instance calling the callback.
  10.623 + * \param  stream_length  A pointer to storage for the length of the stream
  10.624 + *                        in bytes.
  10.625 + * \param  client_data  The callee's client data set through
  10.626 + *                      FLAC__stream_decoder_init_*().
  10.627 + * \retval FLAC__StreamDecoderLengthStatus
  10.628 + *    The callee's return status.
  10.629 + */
  10.630 +typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  10.631 +
  10.632 +/** Signature for the EOF callback.
  10.633 + *
  10.634 + *  A function pointer matching this signature may be passed to
  10.635 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  10.636 + *  called when the decoder needs to know if the end of the stream has
  10.637 + *  been reached.
  10.638 + *
  10.639 + * Here is an example of a EOF callback for stdio streams:
  10.640 + * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
  10.641 + * \code
  10.642 + * {
  10.643 + *   FILE *file = ((MyClientData*)client_data)->file;
  10.644 + *   return feof(file)? true : false;
  10.645 + * }
  10.646 + * \endcode
  10.647 + *
  10.648 + * \note In general, FLAC__StreamDecoder functions which change the
  10.649 + * state should not be called on the \a decoder while in the callback.
  10.650 + *
  10.651 + * \param  decoder  The decoder instance calling the callback.
  10.652 + * \param  client_data  The callee's client data set through
  10.653 + *                      FLAC__stream_decoder_init_*().
  10.654 + * \retval FLAC__bool
  10.655 + *    \c true if the currently at the end of the stream, else \c false.
  10.656 + */
  10.657 +typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
  10.658 +
  10.659 +/** Signature for the write callback.
  10.660 + *
  10.661 + *  A function pointer matching this signature must be passed to one of
  10.662 + *  the FLAC__stream_decoder_init_*() functions.
  10.663 + *  The supplied function will be called when the decoder has decoded a
  10.664 + *  single audio frame.  The decoder will pass the frame metadata as well
  10.665 + *  as an array of pointers (one for each channel) pointing to the
  10.666 + *  decoded audio.
  10.667 + *
  10.668 + * \note In general, FLAC__StreamDecoder functions which change the
  10.669 + * state should not be called on the \a decoder while in the callback.
  10.670 + *
  10.671 + * \param  decoder  The decoder instance calling the callback.
  10.672 + * \param  frame    The description of the decoded frame.  See
  10.673 + *                  FLAC__Frame.
  10.674 + * \param  buffer   An array of pointers to decoded channels of data.
  10.675 + *                  Each pointer will point to an array of signed
  10.676 + *                  samples of length \a frame->header.blocksize.
  10.677 + *                  Channels will be ordered according to the FLAC
  10.678 + *                  specification; see the documentation for the
  10.679 + *                  <A HREF="../format.html#frame_header">frame header</A>.
  10.680 + * \param  client_data  The callee's client data set through
  10.681 + *                      FLAC__stream_decoder_init_*().
  10.682 + * \retval FLAC__StreamDecoderWriteStatus
  10.683 + *    The callee's return status.
  10.684 + */
  10.685 +typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  10.686 +
  10.687 +/** Signature for the metadata callback.
  10.688 + *
  10.689 + *  A function pointer matching this signature must be passed to one of
  10.690 + *  the FLAC__stream_decoder_init_*() functions.
  10.691 + *  The supplied function will be called when the decoder has decoded a
  10.692 + *  metadata block.  In a valid FLAC file there will always be one
  10.693 + *  \c STREAMINFO block, followed by zero or more other metadata blocks.
  10.694 + *  These will be supplied by the decoder in the same order as they
  10.695 + *  appear in the stream and always before the first audio frame (i.e.
  10.696 + *  write callback).  The metadata block that is passed in must not be
  10.697 + *  modified, and it doesn't live beyond the callback, so you should make
  10.698 + *  a copy of it with FLAC__metadata_object_clone() if you will need it
  10.699 + *  elsewhere.  Since metadata blocks can potentially be large, by
  10.700 + *  default the decoder only calls the metadata callback for the
  10.701 + *  \c STREAMINFO block; you can instruct the decoder to pass or filter
  10.702 + *  other blocks with FLAC__stream_decoder_set_metadata_*() calls.
  10.703 + *
  10.704 + * \note In general, FLAC__StreamDecoder functions which change the
  10.705 + * state should not be called on the \a decoder while in the callback.
  10.706 + *
  10.707 + * \param  decoder  The decoder instance calling the callback.
  10.708 + * \param  metadata The decoded metadata block.
  10.709 + * \param  client_data  The callee's client data set through
  10.710 + *                      FLAC__stream_decoder_init_*().
  10.711 + */
  10.712 +typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  10.713 +
  10.714 +/** Signature for the error callback.
  10.715 + *
  10.716 + *  A function pointer matching this signature must be passed to one of
  10.717 + *  the FLAC__stream_decoder_init_*() functions.
  10.718 + *  The supplied function will be called whenever an error occurs during
  10.719 + *  decoding.
  10.720 + *
  10.721 + * \note In general, FLAC__StreamDecoder functions which change the
  10.722 + * state should not be called on the \a decoder while in the callback.
  10.723 + *
  10.724 + * \param  decoder  The decoder instance calling the callback.
  10.725 + * \param  status   The error encountered by the decoder.
  10.726 + * \param  client_data  The callee's client data set through
  10.727 + *                      FLAC__stream_decoder_init_*().
  10.728 + */
  10.729 +typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  10.730 +
  10.731 +
  10.732 +/***********************************************************************
  10.733 + *
  10.734 + * Class constructor/destructor
  10.735 + *
  10.736 + ***********************************************************************/
  10.737 +
  10.738 +/** Create a new stream decoder instance.  The instance is created with
  10.739 + *  default settings; see the individual FLAC__stream_decoder_set_*()
  10.740 + *  functions for each setting's default.
  10.741 + *
  10.742 + * \retval FLAC__StreamDecoder*
  10.743 + *    \c NULL if there was an error allocating memory, else the new instance.
  10.744 + */
  10.745 +FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
  10.746 +
  10.747 +/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  10.748 + *
  10.749 + * \param decoder  A pointer to an existing decoder.
  10.750 + * \assert
  10.751 + *    \code decoder != NULL \endcode
  10.752 + */
  10.753 +FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  10.754 +
  10.755 +
  10.756 +/***********************************************************************
  10.757 + *
  10.758 + * Public class method prototypes
  10.759 + *
  10.760 + ***********************************************************************/
  10.761 +
  10.762 +/** Set the serial number for the FLAC stream within the Ogg container.
  10.763 + *  The default behavior is to use the serial number of the first Ogg
  10.764 + *  page.  Setting a serial number here will explicitly specify which
  10.765 + *  stream is to be decoded.
  10.766 + *
  10.767 + * \note
  10.768 + * This does not need to be set for native FLAC decoding.
  10.769 + *
  10.770 + * \default \c use serial number of first page
  10.771 + * \param  decoder        A decoder instance to set.
  10.772 + * \param  serial_number  See above.
  10.773 + * \assert
  10.774 + *    \code decoder != NULL \endcode
  10.775 + * \retval FLAC__bool
  10.776 + *    \c false if the decoder is already initialized, else \c true.
  10.777 + */
  10.778 +FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
  10.779 +
  10.780 +/** Set the "MD5 signature checking" flag.  If \c true, the decoder will
  10.781 + *  compute the MD5 signature of the unencoded audio data while decoding
  10.782 + *  and compare it to the signature from the STREAMINFO block, if it
  10.783 + *  exists, during FLAC__stream_decoder_finish().
  10.784 + *
  10.785 + *  MD5 signature checking will be turned off (until the next
  10.786 + *  FLAC__stream_decoder_reset()) if there is no signature in the
  10.787 + *  STREAMINFO block or when a seek is attempted.
  10.788 + *
  10.789 + *  Clients that do not use the MD5 check should leave this off to speed
  10.790 + *  up decoding.
  10.791 + *
  10.792 + * \default \c false
  10.793 + * \param  decoder  A decoder instance to set.
  10.794 + * \param  value    Flag value (see above).
  10.795 + * \assert
  10.796 + *    \code decoder != NULL \endcode
  10.797 + * \retval FLAC__bool
  10.798 + *    \c false if the decoder is already initialized, else \c true.
  10.799 + */
  10.800 +FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
  10.801 +
  10.802 +/** Direct the decoder to pass on all metadata blocks of type \a type.
  10.803 + *
  10.804 + * \default By default, only the \c STREAMINFO block is returned via the
  10.805 + *          metadata callback.
  10.806 + * \param  decoder  A decoder instance to set.
  10.807 + * \param  type     See above.
  10.808 + * \assert
  10.809 + *    \code decoder != NULL \endcode
  10.810 + *    \a type is valid
  10.811 + * \retval FLAC__bool
  10.812 + *    \c false if the decoder is already initialized, else \c true.
  10.813 + */
  10.814 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  10.815 +
  10.816 +/** Direct the decoder to pass on all APPLICATION metadata blocks of the
  10.817 + *  given \a id.
  10.818 + *
  10.819 + * \default By default, only the \c STREAMINFO block is returned via the
  10.820 + *          metadata callback.
  10.821 + * \param  decoder  A decoder instance to set.
  10.822 + * \param  id       See above.
  10.823 + * \assert
  10.824 + *    \code decoder != NULL \endcode
  10.825 + *    \code id != NULL \endcode
  10.826 + * \retval FLAC__bool
  10.827 + *    \c false if the decoder is already initialized, else \c true.
  10.828 + */
  10.829 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  10.830 +
  10.831 +/** Direct the decoder to pass on all metadata blocks of any type.
  10.832 + *
  10.833 + * \default By default, only the \c STREAMINFO block is returned via the
  10.834 + *          metadata callback.
  10.835 + * \param  decoder  A decoder instance to set.
  10.836 + * \assert
  10.837 + *    \code decoder != NULL \endcode
  10.838 + * \retval FLAC__bool
  10.839 + *    \c false if the decoder is already initialized, else \c true.
  10.840 + */
  10.841 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
  10.842 +
  10.843 +/** Direct the decoder to filter out all metadata blocks of type \a type.
  10.844 + *
  10.845 + * \default By default, only the \c STREAMINFO block is returned via the
  10.846 + *          metadata callback.
  10.847 + * \param  decoder  A decoder instance to set.
  10.848 + * \param  type     See above.
  10.849 + * \assert
  10.850 + *    \code decoder != NULL \endcode
  10.851 + *    \a type is valid
  10.852 + * \retval FLAC__bool
  10.853 + *    \c false if the decoder is already initialized, else \c true.
  10.854 + */
  10.855 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  10.856 +
  10.857 +/** Direct the decoder to filter out all APPLICATION metadata blocks of
  10.858 + *  the given \a id.
  10.859 + *
  10.860 + * \default By default, only the \c STREAMINFO block is returned via the
  10.861 + *          metadata callback.
  10.862 + * \param  decoder  A decoder instance to set.
  10.863 + * \param  id       See above.
  10.864 + * \assert
  10.865 + *    \code decoder != NULL \endcode
  10.866 + *    \code id != NULL \endcode
  10.867 + * \retval FLAC__bool
  10.868 + *    \c false if the decoder is already initialized, else \c true.
  10.869 + */
  10.870 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  10.871 +
  10.872 +/** Direct the decoder to filter out all metadata blocks of any type.
  10.873 + *
  10.874 + * \default By default, only the \c STREAMINFO block is returned via the
  10.875 + *          metadata callback.
  10.876 + * \param  decoder  A decoder instance to set.
  10.877 + * \assert
  10.878 + *    \code decoder != NULL \endcode
  10.879 + * \retval FLAC__bool
  10.880 + *    \c false if the decoder is already initialized, else \c true.
  10.881 + */
  10.882 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
  10.883 +
  10.884 +/** Get the current decoder state.
  10.885 + *
  10.886 + * \param  decoder  A decoder instance to query.
  10.887 + * \assert
  10.888 + *    \code decoder != NULL \endcode
  10.889 + * \retval FLAC__StreamDecoderState
  10.890 + *    The current decoder state.
  10.891 + */
  10.892 +FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
  10.893 +
  10.894 +/** Get the current decoder state as a C string.
  10.895 + *
  10.896 + * \param  decoder  A decoder instance to query.
  10.897 + * \assert
  10.898 + *    \code decoder != NULL \endcode
  10.899 + * \retval const char *
  10.900 + *    The decoder state as a C string.  Do not modify the contents.
  10.901 + */
  10.902 +FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
  10.903 +
  10.904 +/** Get the "MD5 signature checking" flag.
  10.905 + *  This is the value of the setting, not whether or not the decoder is
  10.906 + *  currently checking the MD5 (remember, it can be turned off automatically
  10.907 + *  by a seek).  When the decoder is reset the flag will be restored to the
  10.908 + *  value returned by this function.
  10.909 + *
  10.910 + * \param  decoder  A decoder instance to query.
  10.911 + * \assert
  10.912 + *    \code decoder != NULL \endcode
  10.913 + * \retval FLAC__bool
  10.914 + *    See above.
  10.915 + */
  10.916 +FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
  10.917 +
  10.918 +/** Get the total number of samples in the stream being decoded.
  10.919 + *  Will only be valid after decoding has started and will contain the
  10.920 + *  value from the \c STREAMINFO block.  A value of \c 0 means "unknown".
  10.921 + *
  10.922 + * \param  decoder  A decoder instance to query.
  10.923 + * \assert
  10.924 + *    \code decoder != NULL \endcode
  10.925 + * \retval unsigned
  10.926 + *    See above.
  10.927 + */
  10.928 +FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
  10.929 +
  10.930 +/** Get the current number of channels in the stream being decoded.
  10.931 + *  Will only be valid after decoding has started and will contain the
  10.932 + *  value from the most recently decoded frame header.
  10.933 + *
  10.934 + * \param  decoder  A decoder instance to query.
  10.935 + * \assert
  10.936 + *    \code decoder != NULL \endcode
  10.937 + * \retval unsigned
  10.938 + *    See above.
  10.939 + */
  10.940 +FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
  10.941 +
  10.942 +/** Get the current channel assignment in the stream being decoded.
  10.943 + *  Will only be valid after decoding has started and will contain the
  10.944 + *  value from the most recently decoded frame header.
  10.945 + *
  10.946 + * \param  decoder  A decoder instance to query.
  10.947 + * \assert
  10.948 + *    \code decoder != NULL \endcode
  10.949 + * \retval FLAC__ChannelAssignment
  10.950 + *    See above.
  10.951 + */
  10.952 +FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
  10.953 +
  10.954 +/** Get the current sample resolution in the stream being decoded.
  10.955 + *  Will only be valid after decoding has started and will contain the
  10.956 + *  value from the most recently decoded frame header.
  10.957 + *
  10.958 + * \param  decoder  A decoder instance to query.
  10.959 + * \assert
  10.960 + *    \code decoder != NULL \endcode
  10.961 + * \retval unsigned
  10.962 + *    See above.
  10.963 + */
  10.964 +FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
  10.965 +
  10.966 +/** Get the current sample rate in Hz of the stream being decoded.
  10.967 + *  Will only be valid after decoding has started and will contain the
  10.968 + *  value from the most recently decoded frame header.
  10.969 + *
  10.970 + * \param  decoder  A decoder instance to query.
  10.971 + * \assert
  10.972 + *    \code decoder != NULL \endcode
  10.973 + * \retval unsigned
  10.974 + *    See above.
  10.975 + */
  10.976 +FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
  10.977 +
  10.978 +/** Get the current blocksize of the stream being decoded.
  10.979 + *  Will only be valid after decoding has started and will contain the
  10.980 + *  value from the most recently decoded frame header.
  10.981 + *
  10.982 + * \param  decoder  A decoder instance to query.
  10.983 + * \assert
  10.984 + *    \code decoder != NULL \endcode
  10.985 + * \retval unsigned
  10.986 + *    See above.
  10.987 + */
  10.988 +FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
  10.989 +
  10.990 +/** Returns the decoder's current read position within the stream.
  10.991 + *  The position is the byte offset from the start of the stream.
  10.992 + *  Bytes before this position have been fully decoded.  Note that
  10.993 + *  there may still be undecoded bytes in the decoder's read FIFO.
  10.994 + *  The returned position is correct even after a seek.
  10.995 + *
  10.996 + *  \warning This function currently only works for native FLAC,
  10.997 + *           not Ogg FLAC streams.
  10.998 + *
  10.999 + * \param  decoder   A decoder instance to query.
 10.1000 + * \param  position  Address at which to return the desired position.
 10.1001 + * \assert
 10.1002 + *    \code decoder != NULL \endcode
 10.1003 + *    \code position != NULL \endcode
 10.1004 + * \retval FLAC__bool
 10.1005 + *    \c true if successful, \c false if the stream is not native FLAC,
 10.1006 + *    or there was an error from the 'tell' callback or it returned
 10.1007 + *    \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
 10.1008 + */
 10.1009 +FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
 10.1010 +
 10.1011 +/** Initialize the decoder instance to decode native FLAC streams.
 10.1012 + *
 10.1013 + *  This flavor of initialization sets up the decoder to decode from a
 10.1014 + *  native FLAC stream. I/O is performed via callbacks to the client.
 10.1015 + *  For decoding from a plain file via filename or open FILE*,
 10.1016 + *  FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
 10.1017 + *  provide a simpler interface.
 10.1018 + *
 10.1019 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1020 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1021 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1022 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1023 + *  if initialization succeeded.
 10.1024 + *
 10.1025 + * \param  decoder            An uninitialized decoder instance.
 10.1026 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 10.1027 + *                            pointer must not be \c NULL.
 10.1028 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 10.1029 + *                            pointer may be \c NULL if seeking is not
 10.1030 + *                            supported.  If \a seek_callback is not \c NULL then a
 10.1031 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 10.1032 + *                            Alternatively, a dummy seek callback that just
 10.1033 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 10.1034 + *                            may also be supplied, all though this is slightly
 10.1035 + *                            less efficient for the decoder.
 10.1036 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 10.1037 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1038 + *                            \a seek_callback is not \c NULL then a
 10.1039 + *                            \a tell_callback must also be supplied.
 10.1040 + *                            Alternatively, a dummy tell callback that just
 10.1041 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 10.1042 + *                            may also be supplied, all though this is slightly
 10.1043 + *                            less efficient for the decoder.
 10.1044 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 10.1045 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1046 + *                            \a seek_callback is not \c NULL then a
 10.1047 + *                            \a length_callback must also be supplied.
 10.1048 + *                            Alternatively, a dummy length callback that just
 10.1049 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 10.1050 + *                            may also be supplied, all though this is slightly
 10.1051 + *                            less efficient for the decoder.
 10.1052 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 10.1053 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1054 + *                            \a seek_callback is not \c NULL then a
 10.1055 + *                            \a eof_callback must also be supplied.
 10.1056 + *                            Alternatively, a dummy length callback that just
 10.1057 + *                            returns \c false
 10.1058 + *                            may also be supplied, all though this is slightly
 10.1059 + *                            less efficient for the decoder.
 10.1060 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1061 + *                            pointer must not be \c NULL.
 10.1062 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1063 + *                            pointer may be \c NULL if the callback is not
 10.1064 + *                            desired.
 10.1065 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1066 + *                            pointer must not be \c NULL.
 10.1067 + * \param  client_data        This value will be supplied to callbacks in their
 10.1068 + *                            \a client_data argument.
 10.1069 + * \assert
 10.1070 + *    \code decoder != NULL \endcode
 10.1071 + * \retval FLAC__StreamDecoderInitStatus
 10.1072 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1073 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1074 + */
 10.1075 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
 10.1076 +	FLAC__StreamDecoder *decoder,
 10.1077 +	FLAC__StreamDecoderReadCallback read_callback,
 10.1078 +	FLAC__StreamDecoderSeekCallback seek_callback,
 10.1079 +	FLAC__StreamDecoderTellCallback tell_callback,
 10.1080 +	FLAC__StreamDecoderLengthCallback length_callback,
 10.1081 +	FLAC__StreamDecoderEofCallback eof_callback,
 10.1082 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1083 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1084 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1085 +	void *client_data
 10.1086 +);
 10.1087 +
 10.1088 +/** Initialize the decoder instance to decode Ogg FLAC streams.
 10.1089 + *
 10.1090 + *  This flavor of initialization sets up the decoder to decode from a
 10.1091 + *  FLAC stream in an Ogg container. I/O is performed via callbacks to the
 10.1092 + *  client.  For decoding from a plain file via filename or open FILE*,
 10.1093 + *  FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
 10.1094 + *  provide a simpler interface.
 10.1095 + *
 10.1096 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1097 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1098 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1099 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1100 + *  if initialization succeeded.
 10.1101 + *
 10.1102 + *  \note Support for Ogg FLAC in the library is optional.  If this
 10.1103 + *  library has been built without support for Ogg FLAC, this function
 10.1104 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 10.1105 + *
 10.1106 + * \param  decoder            An uninitialized decoder instance.
 10.1107 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 10.1108 + *                            pointer must not be \c NULL.
 10.1109 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 10.1110 + *                            pointer may be \c NULL if seeking is not
 10.1111 + *                            supported.  If \a seek_callback is not \c NULL then a
 10.1112 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 10.1113 + *                            Alternatively, a dummy seek callback that just
 10.1114 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 10.1115 + *                            may also be supplied, all though this is slightly
 10.1116 + *                            less efficient for the decoder.
 10.1117 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 10.1118 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1119 + *                            \a seek_callback is not \c NULL then a
 10.1120 + *                            \a tell_callback must also be supplied.
 10.1121 + *                            Alternatively, a dummy tell callback that just
 10.1122 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 10.1123 + *                            may also be supplied, all though this is slightly
 10.1124 + *                            less efficient for the decoder.
 10.1125 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 10.1126 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1127 + *                            \a seek_callback is not \c NULL then a
 10.1128 + *                            \a length_callback must also be supplied.
 10.1129 + *                            Alternatively, a dummy length callback that just
 10.1130 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 10.1131 + *                            may also be supplied, all though this is slightly
 10.1132 + *                            less efficient for the decoder.
 10.1133 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 10.1134 + *                            pointer may be \c NULL if not supported by the client.  If
 10.1135 + *                            \a seek_callback is not \c NULL then a
 10.1136 + *                            \a eof_callback must also be supplied.
 10.1137 + *                            Alternatively, a dummy length callback that just
 10.1138 + *                            returns \c false
 10.1139 + *                            may also be supplied, all though this is slightly
 10.1140 + *                            less efficient for the decoder.
 10.1141 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1142 + *                            pointer must not be \c NULL.
 10.1143 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1144 + *                            pointer may be \c NULL if the callback is not
 10.1145 + *                            desired.
 10.1146 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1147 + *                            pointer must not be \c NULL.
 10.1148 + * \param  client_data        This value will be supplied to callbacks in their
 10.1149 + *                            \a client_data argument.
 10.1150 + * \assert
 10.1151 + *    \code decoder != NULL \endcode
 10.1152 + * \retval FLAC__StreamDecoderInitStatus
 10.1153 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1154 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1155 + */
 10.1156 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
 10.1157 +	FLAC__StreamDecoder *decoder,
 10.1158 +	FLAC__StreamDecoderReadCallback read_callback,
 10.1159 +	FLAC__StreamDecoderSeekCallback seek_callback,
 10.1160 +	FLAC__StreamDecoderTellCallback tell_callback,
 10.1161 +	FLAC__StreamDecoderLengthCallback length_callback,
 10.1162 +	FLAC__StreamDecoderEofCallback eof_callback,
 10.1163 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1164 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1165 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1166 +	void *client_data
 10.1167 +);
 10.1168 +
 10.1169 +/** Initialize the decoder instance to decode native FLAC files.
 10.1170 + *
 10.1171 + *  This flavor of initialization sets up the decoder to decode from a
 10.1172 + *  plain native FLAC file.  For non-stdio streams, you must use
 10.1173 + *  FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
 10.1174 + *
 10.1175 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1176 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1177 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1178 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1179 + *  if initialization succeeded.
 10.1180 + *
 10.1181 + * \param  decoder            An uninitialized decoder instance.
 10.1182 + * \param  file               An open FLAC file.  The file should have been
 10.1183 + *                            opened with mode \c "rb" and rewound.  The file
 10.1184 + *                            becomes owned by the decoder and should not be
 10.1185 + *                            manipulated by the client while decoding.
 10.1186 + *                            Unless \a file is \c stdin, it will be closed
 10.1187 + *                            when FLAC__stream_decoder_finish() is called.
 10.1188 + *                            Note however that seeking will not work when
 10.1189 + *                            decoding from \c stdout since it is not seekable.
 10.1190 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1191 + *                            pointer must not be \c NULL.
 10.1192 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1193 + *                            pointer may be \c NULL if the callback is not
 10.1194 + *                            desired.
 10.1195 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1196 + *                            pointer must not be \c NULL.
 10.1197 + * \param  client_data        This value will be supplied to callbacks in their
 10.1198 + *                            \a client_data argument.
 10.1199 + * \assert
 10.1200 + *    \code decoder != NULL \endcode
 10.1201 + *    \code file != NULL \endcode
 10.1202 + * \retval FLAC__StreamDecoderInitStatus
 10.1203 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1204 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1205 + */
 10.1206 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
 10.1207 +	FLAC__StreamDecoder *decoder,
 10.1208 +	FILE *file,
 10.1209 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1210 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1211 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1212 +	void *client_data
 10.1213 +);
 10.1214 +
 10.1215 +/** Initialize the decoder instance to decode Ogg FLAC files.
 10.1216 + *
 10.1217 + *  This flavor of initialization sets up the decoder to decode from a
 10.1218 + *  plain Ogg FLAC file.  For non-stdio streams, you must use
 10.1219 + *  FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
 10.1220 + *
 10.1221 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1222 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1223 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1224 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1225 + *  if initialization succeeded.
 10.1226 + *
 10.1227 + *  \note Support for Ogg FLAC in the library is optional.  If this
 10.1228 + *  library has been built without support for Ogg FLAC, this function
 10.1229 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 10.1230 + *
 10.1231 + * \param  decoder            An uninitialized decoder instance.
 10.1232 + * \param  file               An open FLAC file.  The file should have been
 10.1233 + *                            opened with mode \c "rb" and rewound.  The file
 10.1234 + *                            becomes owned by the decoder and should not be
 10.1235 + *                            manipulated by the client while decoding.
 10.1236 + *                            Unless \a file is \c stdin, it will be closed
 10.1237 + *                            when FLAC__stream_decoder_finish() is called.
 10.1238 + *                            Note however that seeking will not work when
 10.1239 + *                            decoding from \c stdout since it is not seekable.
 10.1240 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1241 + *                            pointer must not be \c NULL.
 10.1242 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1243 + *                            pointer may be \c NULL if the callback is not
 10.1244 + *                            desired.
 10.1245 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1246 + *                            pointer must not be \c NULL.
 10.1247 + * \param  client_data        This value will be supplied to callbacks in their
 10.1248 + *                            \a client_data argument.
 10.1249 + * \assert
 10.1250 + *    \code decoder != NULL \endcode
 10.1251 + *    \code file != NULL \endcode
 10.1252 + * \retval FLAC__StreamDecoderInitStatus
 10.1253 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1254 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1255 + */
 10.1256 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
 10.1257 +	FLAC__StreamDecoder *decoder,
 10.1258 +	FILE *file,
 10.1259 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1260 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1261 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1262 +	void *client_data
 10.1263 +);
 10.1264 +
 10.1265 +/** Initialize the decoder instance to decode native FLAC files.
 10.1266 + *
 10.1267 + *  This flavor of initialization sets up the decoder to decode from a plain
 10.1268 + *  native FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 10.1269 + *  example, with Unicode filenames on Windows), you must use
 10.1270 + *  FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
 10.1271 + *  and provide callbacks for the I/O.
 10.1272 + *
 10.1273 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1274 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1275 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1276 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1277 + *  if initialization succeeded.
 10.1278 + *
 10.1279 + * \param  decoder            An uninitialized decoder instance.
 10.1280 + * \param  filename           The name of the file to decode from.  The file will
 10.1281 + *                            be opened with fopen().  Use \c NULL to decode from
 10.1282 + *                            \c stdin.  Note that \c stdin is not seekable.
 10.1283 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1284 + *                            pointer must not be \c NULL.
 10.1285 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1286 + *                            pointer may be \c NULL if the callback is not
 10.1287 + *                            desired.
 10.1288 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1289 + *                            pointer must not be \c NULL.
 10.1290 + * \param  client_data        This value will be supplied to callbacks in their
 10.1291 + *                            \a client_data argument.
 10.1292 + * \assert
 10.1293 + *    \code decoder != NULL \endcode
 10.1294 + * \retval FLAC__StreamDecoderInitStatus
 10.1295 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1296 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1297 + */
 10.1298 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
 10.1299 +	FLAC__StreamDecoder *decoder,
 10.1300 +	const char *filename,
 10.1301 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1302 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1303 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1304 +	void *client_data
 10.1305 +);
 10.1306 +
 10.1307 +/** Initialize the decoder instance to decode Ogg FLAC files.
 10.1308 + *
 10.1309 + *  This flavor of initialization sets up the decoder to decode from a plain
 10.1310 + *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 10.1311 + *  example, with Unicode filenames on Windows), you must use
 10.1312 + *  FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
 10.1313 + *  and provide callbacks for the I/O.
 10.1314 + *
 10.1315 + *  This function should be called after FLAC__stream_decoder_new() and
 10.1316 + *  FLAC__stream_decoder_set_*() but before any of the
 10.1317 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 10.1318 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 10.1319 + *  if initialization succeeded.
 10.1320 + *
 10.1321 + *  \note Support for Ogg FLAC in the library is optional.  If this
 10.1322 + *  library has been built without support for Ogg FLAC, this function
 10.1323 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 10.1324 + *
 10.1325 + * \param  decoder            An uninitialized decoder instance.
 10.1326 + * \param  filename           The name of the file to decode from.  The file will
 10.1327 + *                            be opened with fopen().  Use \c NULL to decode from
 10.1328 + *                            \c stdin.  Note that \c stdin is not seekable.
 10.1329 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 10.1330 + *                            pointer must not be \c NULL.
 10.1331 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 10.1332 + *                            pointer may be \c NULL if the callback is not
 10.1333 + *                            desired.
 10.1334 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 10.1335 + *                            pointer must not be \c NULL.
 10.1336 + * \param  client_data        This value will be supplied to callbacks in their
 10.1337 + *                            \a client_data argument.
 10.1338 + * \assert
 10.1339 + *    \code decoder != NULL \endcode
 10.1340 + * \retval FLAC__StreamDecoderInitStatus
 10.1341 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 10.1342 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 10.1343 + */
 10.1344 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
 10.1345 +	FLAC__StreamDecoder *decoder,
 10.1346 +	const char *filename,
 10.1347 +	FLAC__StreamDecoderWriteCallback write_callback,
 10.1348 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 10.1349 +	FLAC__StreamDecoderErrorCallback error_callback,
 10.1350 +	void *client_data
 10.1351 +);
 10.1352 +
 10.1353 +/** Finish the decoding process.
 10.1354 + *  Flushes the decoding buffer, releases resources, resets the decoder
 10.1355 + *  settings to their defaults, and returns the decoder state to
 10.1356 + *  FLAC__STREAM_DECODER_UNINITIALIZED.
 10.1357 + *
 10.1358 + *  In the event of a prematurely-terminated decode, it is not strictly
 10.1359 + *  necessary to call this immediately before FLAC__stream_decoder_delete()
 10.1360 + *  but it is good practice to match every FLAC__stream_decoder_init_*()
 10.1361 + *  with a FLAC__stream_decoder_finish().
 10.1362 + *
 10.1363 + * \param  decoder  An uninitialized decoder instance.
 10.1364 + * \assert
 10.1365 + *    \code decoder != NULL \endcode
 10.1366 + * \retval FLAC__bool
 10.1367 + *    \c false if MD5 checking is on AND a STREAMINFO block was available
 10.1368 + *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 10.1369 + *    signature does not match the one computed by the decoder; else
 10.1370 + *    \c true.
 10.1371 + */
 10.1372 +FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
 10.1373 +
 10.1374 +/** Flush the stream input.
 10.1375 + *  The decoder's input buffer will be cleared and the state set to
 10.1376 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.  This will also turn
 10.1377 + *  off MD5 checking.
 10.1378 + *
 10.1379 + * \param  decoder  A decoder instance.
 10.1380 + * \assert
 10.1381 + *    \code decoder != NULL \endcode
 10.1382 + * \retval FLAC__bool
 10.1383 + *    \c true if successful, else \c false if a memory allocation
 10.1384 + *    error occurs (in which case the state will be set to
 10.1385 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
 10.1386 + */
 10.1387 +FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
 10.1388 +
 10.1389 +/** Reset the decoding process.
 10.1390 + *  The decoder's input buffer will be cleared and the state set to
 10.1391 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
 10.1392 + *  FLAC__stream_decoder_finish() except that the settings are
 10.1393 + *  preserved; there is no need to call FLAC__stream_decoder_init_*()
 10.1394 + *  before decoding again.  MD5 checking will be restored to its original
 10.1395 + *  setting.
 10.1396 + *
 10.1397 + *  If the decoder is seekable, or was initialized with
 10.1398 + *  FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
 10.1399 + *  the decoder will also attempt to seek to the beginning of the file.
 10.1400 + *  If this rewind fails, this function will return \c false.  It follows
 10.1401 + *  that FLAC__stream_decoder_reset() cannot be used when decoding from
 10.1402 + *  \c stdin.
 10.1403 + *
 10.1404 + *  If the decoder was initialized with FLAC__stream_encoder_init*_stream()
 10.1405 + *  and is not seekable (i.e. no seek callback was provided or the seek
 10.1406 + *  callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
 10.1407 + *  is the duty of the client to start feeding data from the beginning of
 10.1408 + *  the stream on the next FLAC__stream_decoder_process() or
 10.1409 + *  FLAC__stream_decoder_process_interleaved() call.
 10.1410 + *
 10.1411 + * \param  decoder  A decoder instance.
 10.1412 + * \assert
 10.1413 + *    \code decoder != NULL \endcode
 10.1414 + * \retval FLAC__bool
 10.1415 + *    \c true if successful, else \c false if a memory allocation occurs
 10.1416 + *    (in which case the state will be set to
 10.1417 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
 10.1418 + *    occurs (the state will be unchanged).
 10.1419 + */
 10.1420 +FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
 10.1421 +
 10.1422 +/** Decode one metadata block or audio frame.
 10.1423 + *  This version instructs the decoder to decode a either a single metadata
 10.1424 + *  block or a single frame and stop, unless the callbacks return a fatal
 10.1425 + *  error or the read callback returns
 10.1426 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 10.1427 + *
 10.1428 + *  As the decoder needs more input it will call the read callback.
 10.1429 + *  Depending on what was decoded, the metadata or write callback will be
 10.1430 + *  called with the decoded metadata block or audio frame.
 10.1431 + *
 10.1432 + *  Unless there is a fatal read error or end of stream, this function
 10.1433 + *  will return once one whole frame is decoded.  In other words, if the
 10.1434 + *  stream is not synchronized or points to a corrupt frame header, the
 10.1435 + *  decoder will continue to try and resync until it gets to a valid
 10.1436 + *  frame, then decode one frame, then return.  If the decoder points to
 10.1437 + *  a frame whose frame CRC in the frame footer does not match the
 10.1438 + *  computed frame CRC, this function will issue a
 10.1439 + *  FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
 10.1440 + *  error callback, and return, having decoded one complete, although
 10.1441 + *  corrupt, frame.  (Such corrupted frames are sent as silence of the
 10.1442 + *  correct length to the write callback.)
 10.1443 + *
 10.1444 + * \param  decoder  An initialized decoder instance.
 10.1445 + * \assert
 10.1446 + *    \code decoder != NULL \endcode
 10.1447 + * \retval FLAC__bool
 10.1448 + *    \c false if any fatal read, write, or memory allocation error
 10.1449 + *    occurred (meaning decoding must stop), else \c true; for more
 10.1450 + *    information about the decoder, check the decoder state with
 10.1451 + *    FLAC__stream_decoder_get_state().
 10.1452 + */
 10.1453 +FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
 10.1454 +
 10.1455 +/** Decode until the end of the metadata.
 10.1456 + *  This version instructs the decoder to decode from the current position
 10.1457 + *  and continue until all the metadata has been read, or until the
 10.1458 + *  callbacks return a fatal error or the read callback returns
 10.1459 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 10.1460 + *
 10.1461 + *  As the decoder needs more input it will call the read callback.
 10.1462 + *  As each metadata block is decoded, the metadata callback will be called
 10.1463 + *  with the decoded metadata.
 10.1464 + *
 10.1465 + * \param  decoder  An initialized decoder instance.
 10.1466 + * \assert
 10.1467 + *    \code decoder != NULL \endcode
 10.1468 + * \retval FLAC__bool
 10.1469 + *    \c false if any fatal read, write, or memory allocation error
 10.1470 + *    occurred (meaning decoding must stop), else \c true; for more
 10.1471 + *    information about the decoder, check the decoder state with
 10.1472 + *    FLAC__stream_decoder_get_state().
 10.1473 + */
 10.1474 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
 10.1475 +
 10.1476 +/** Decode until the end of the stream.
 10.1477 + *  This version instructs the decoder to decode from the current position
 10.1478 + *  and continue until the end of stream (the read callback returns
 10.1479 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
 10.1480 + *  callbacks return a fatal error.
 10.1481 + *
 10.1482 + *  As the decoder needs more input it will call the read callback.
 10.1483 + *  As each metadata block and frame is decoded, the metadata or write
 10.1484 + *  callback will be called with the decoded metadata or frame.
 10.1485 + *
 10.1486 + * \param  decoder  An initialized decoder instance.
 10.1487 + * \assert
 10.1488 + *    \code decoder != NULL \endcode
 10.1489 + * \retval FLAC__bool
 10.1490 + *    \c false if any fatal read, write, or memory allocation error
 10.1491 + *    occurred (meaning decoding must stop), else \c true; for more
 10.1492 + *    information about the decoder, check the decoder state with
 10.1493 + *    FLAC__stream_decoder_get_state().
 10.1494 + */
 10.1495 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
 10.1496 +
 10.1497 +/** Skip one audio frame.
 10.1498 + *  This version instructs the decoder to 'skip' a single frame and stop,
 10.1499 + *  unless the callbacks return a fatal error or the read callback returns
 10.1500 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 10.1501 + *
 10.1502 + *  The decoding flow is the same as what occurs when
 10.1503 + *  FLAC__stream_decoder_process_single() is called to process an audio
 10.1504 + *  frame, except that this function does not decode the parsed data into
 10.1505 + *  PCM or call the write callback.  The integrity of the frame is still
 10.1506 + *  checked the same way as in the other process functions.
 10.1507 + *
 10.1508 + *  This function will return once one whole frame is skipped, in the
 10.1509 + *  same way that FLAC__stream_decoder_process_single() will return once
 10.1510 + *  one whole frame is decoded.
 10.1511 + *
 10.1512 + *  This function can be used in more quickly determining FLAC frame
 10.1513 + *  boundaries when decoding of the actual data is not needed, for
 10.1514 + *  example when an application is separating a FLAC stream into frames
 10.1515 + *  for editing or storing in a container.  To do this, the application
 10.1516 + *  can use FLAC__stream_decoder_skip_single_frame() to quickly advance
 10.1517 + *  to the next frame, then use
 10.1518 + *  FLAC__stream_decoder_get_decode_position() to find the new frame
 10.1519 + *  boundary.
 10.1520 + *
 10.1521 + *  This function should only be called when the stream has advanced
 10.1522 + *  past all the metadata, otherwise it will return \c false.
 10.1523 + *
 10.1524 + * \param  decoder  An initialized decoder instance not in a metadata
 10.1525 + *                  state.
 10.1526 + * \assert
 10.1527 + *    \code decoder != NULL \endcode
 10.1528 + * \retval FLAC__bool
 10.1529 + *    \c false if any fatal read, write, or memory allocation error
 10.1530 + *    occurred (meaning decoding must stop), or if the decoder
 10.1531 + *    is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
 10.1532 + *    FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
 10.1533 + *    information about the decoder, check the decoder state with
 10.1534 + *    FLAC__stream_decoder_get_state().
 10.1535 + */
 10.1536 +FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
 10.1537 +
 10.1538 +/** Flush the input and seek to an absolute sample.
 10.1539 + *  Decoding will resume at the given sample.  Note that because of
 10.1540 + *  this, the next write callback may contain a partial block.  The
 10.1541 + *  client must support seeking the input or this function will fail
 10.1542 + *  and return \c false.  Furthermore, if the decoder state is
 10.1543 + *  \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
 10.1544 + *  with FLAC__stream_decoder_flush() or reset with
 10.1545 + *  FLAC__stream_decoder_reset() before decoding can continue.
 10.1546 + *
 10.1547 + * \param  decoder  A decoder instance.
 10.1548 + * \param  sample   The target sample number to seek to.
 10.1549 + * \assert
 10.1550 + *    \code decoder != NULL \endcode
 10.1551 + * \retval FLAC__bool
 10.1552 + *    \c true if successful, else \c false.
 10.1553 + */
 10.1554 +FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
 10.1555 +
 10.1556 +/* \} */
 10.1557 +
 10.1558 +#ifdef __cplusplus
 10.1559 +}
 10.1560 +#endif
 10.1561 +
 10.1562 +#endif
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/VisualC/external/include/FLAC/stream_encoder.h	Mon Jan 09 04:20:54 2012 -0500
    11.3 @@ -0,0 +1,1768 @@
    11.4 +/* libFLAC - Free Lossless Audio Codec library
    11.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    11.6 + *
    11.7 + * Redistribution and use in source and binary forms, with or without
    11.8 + * modification, are permitted provided that the following conditions
    11.9 + * are met:
   11.10 + *
   11.11 + * - Redistributions of source code must retain the above copyright
   11.12 + * notice, this list of conditions and the following disclaimer.
   11.13 + *
   11.14 + * - Redistributions in binary form must reproduce the above copyright
   11.15 + * notice, this list of conditions and the following disclaimer in the
   11.16 + * documentation and/or other materials provided with the distribution.
   11.17 + *
   11.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   11.19 + * contributors may be used to endorse or promote products derived from
   11.20 + * this software without specific prior written permission.
   11.21 + *
   11.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   11.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   11.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   11.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   11.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   11.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   11.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   11.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   11.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   11.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   11.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   11.33 + */
   11.34 +
   11.35 +#ifndef FLAC__STREAM_ENCODER_H
   11.36 +#define FLAC__STREAM_ENCODER_H
   11.37 +
   11.38 +#include <stdio.h> /* for FILE */
   11.39 +#include "export.h"
   11.40 +#include "format.h"
   11.41 +#include "stream_decoder.h"
   11.42 +
   11.43 +#ifdef __cplusplus
   11.44 +extern "C" {
   11.45 +#endif
   11.46 +
   11.47 +
   11.48 +/** \file include/FLAC/stream_encoder.h
   11.49 + *
   11.50 + *  \brief
   11.51 + *  This module contains the functions which implement the stream
   11.52 + *  encoder.
   11.53 + *
   11.54 + *  See the detailed documentation in the
   11.55 + *  \link flac_stream_encoder stream encoder \endlink module.
   11.56 + */
   11.57 +
   11.58 +/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
   11.59 + *  \ingroup flac
   11.60 + *
   11.61 + *  \brief
   11.62 + *  This module describes the encoder layers provided by libFLAC.
   11.63 + *
   11.64 + * The stream encoder can be used to encode complete streams either to the
   11.65 + * client via callbacks, or directly to a file, depending on how it is
   11.66 + * initialized.  When encoding via callbacks, the client provides a write
   11.67 + * callback which will be called whenever FLAC data is ready to be written.
   11.68 + * If the client also supplies a seek callback, the encoder will also
   11.69 + * automatically handle the writing back of metadata discovered while
   11.70 + * encoding, like stream info, seek points offsets, etc.  When encoding to
   11.71 + * a file, the client needs only supply a filename or open \c FILE* and an
   11.72 + * optional progress callback for periodic notification of progress; the
   11.73 + * write and seek callbacks are supplied internally.  For more info see the
   11.74 + * \link flac_stream_encoder stream encoder \endlink module.
   11.75 + */
   11.76 +
   11.77 +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
   11.78 + *  \ingroup flac_encoder
   11.79 + *
   11.80 + *  \brief
   11.81 + *  This module contains the functions which implement the stream
   11.82 + *  encoder.
   11.83 + *
   11.84 + * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
   11.85 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   11.86 + *
   11.87 + * The basic usage of this encoder is as follows:
   11.88 + * - The program creates an instance of an encoder using
   11.89 + *   FLAC__stream_encoder_new().
   11.90 + * - The program overrides the default settings using
   11.91 + *   FLAC__stream_encoder_set_*() functions.  At a minimum, the following
   11.92 + *   functions should be called:
   11.93 + *   - FLAC__stream_encoder_set_channels()
   11.94 + *   - FLAC__stream_encoder_set_bits_per_sample()
   11.95 + *   - FLAC__stream_encoder_set_sample_rate()
   11.96 + *   - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
   11.97 + *   - FLAC__stream_encoder_set_total_samples_estimate() (if known)
   11.98 + * - If the application wants to control the compression level or set its own
   11.99 + *   metadata, then the following should also be called:
  11.100 + *   - FLAC__stream_encoder_set_compression_level()
  11.101 + *   - FLAC__stream_encoder_set_verify()
  11.102 + *   - FLAC__stream_encoder_set_metadata()
  11.103 + * - The rest of the set functions should only be called if the client needs
  11.104 + *   exact control over how the audio is compressed; thorough understanding
  11.105 + *   of the FLAC format is necessary to achieve good results.
  11.106 + * - The program initializes the instance to validate the settings and
  11.107 + *   prepare for encoding using
  11.108 + *   - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
  11.109 + *     or FLAC__stream_encoder_init_file() for native FLAC
  11.110 + *   - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
  11.111 + *     or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
  11.112 + * - The program calls FLAC__stream_encoder_process() or
  11.113 + *   FLAC__stream_encoder_process_interleaved() to encode data, which
  11.114 + *   subsequently calls the callbacks when there is encoder data ready
  11.115 + *   to be written.
  11.116 + * - The program finishes the encoding with FLAC__stream_encoder_finish(),
  11.117 + *   which causes the encoder to encode any data still in its input pipe,
  11.118 + *   update the metadata with the final encoding statistics if output
  11.119 + *   seeking is possible, and finally reset the encoder to the
  11.120 + *   uninitialized state.
  11.121 + * - The instance may be used again or deleted with
  11.122 + *   FLAC__stream_encoder_delete().
  11.123 + *
  11.124 + * In more detail, the stream encoder functions similarly to the
  11.125 + * \link flac_stream_decoder stream decoder \endlink, but has fewer
  11.126 + * callbacks and more options.  Typically the client will create a new
  11.127 + * instance by calling FLAC__stream_encoder_new(), then set the necessary
  11.128 + * parameters with FLAC__stream_encoder_set_*(), and initialize it by
  11.129 + * calling one of the FLAC__stream_encoder_init_*() functions.
  11.130 + *
  11.131 + * Unlike the decoders, the stream encoder has many options that can
  11.132 + * affect the speed and compression ratio.  When setting these parameters
  11.133 + * you should have some basic knowledge of the format (see the
  11.134 + * <A HREF="../documentation.html#format">user-level documentation</A>
  11.135 + * or the <A HREF="../format.html">formal description</A>).  The
  11.136 + * FLAC__stream_encoder_set_*() functions themselves do not validate the
  11.137 + * values as many are interdependent.  The FLAC__stream_encoder_init_*()
  11.138 + * functions will do this, so make sure to pay attention to the state
  11.139 + * returned by FLAC__stream_encoder_init_*() to make sure that it is
  11.140 + * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
  11.141 + * before FLAC__stream_encoder_init_*() will take on the defaults from
  11.142 + * the constructor.
  11.143 + *
  11.144 + * There are three initialization functions for native FLAC, one for
  11.145 + * setting up the encoder to encode FLAC data to the client via
  11.146 + * callbacks, and two for encoding directly to a file.
  11.147 + *
  11.148 + * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
  11.149 + * You must also supply a write callback which will be called anytime
  11.150 + * there is raw encoded data to write.  If the client can seek the output
  11.151 + * it is best to also supply seek and tell callbacks, as this allows the
  11.152 + * encoder to go back after encoding is finished to write back
  11.153 + * information that was collected while encoding, like seek point offsets,
  11.154 + * frame sizes, etc.
  11.155 + *
  11.156 + * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
  11.157 + * or FLAC__stream_encoder_init_file().  Then you must only supply a
  11.158 + * filename or open \c FILE*; the encoder will handle all the callbacks
  11.159 + * internally.  You may also supply a progress callback for periodic
  11.160 + * notification of the encoding progress.
  11.161 + *
  11.162 + * There are three similarly-named init functions for encoding to Ogg
  11.163 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  11.164 + * library has been built with Ogg support.
  11.165 + *
  11.166 + * The call to FLAC__stream_encoder_init_*() currently will also immediately
  11.167 + * call the write callback several times, once with the \c fLaC signature,
  11.168 + * and once for each encoded metadata block.  Note that for Ogg FLAC
  11.169 + * encoding you will usually get at least twice the number of callbacks than
  11.170 + * with native FLAC, one for the Ogg page header and one for the page body.
  11.171 + *
  11.172 + * After initializing the instance, the client may feed audio data to the
  11.173 + * encoder in one of two ways:
  11.174 + *
  11.175 + * - Channel separate, through FLAC__stream_encoder_process() - The client
  11.176 + *   will pass an array of pointers to buffers, one for each channel, to
  11.177 + *   the encoder, each of the same length.  The samples need not be
  11.178 + *   block-aligned, but each channel should have the same number of samples.
  11.179 + * - Channel interleaved, through
  11.180 + *   FLAC__stream_encoder_process_interleaved() - The client will pass a single
  11.181 + *   pointer to data that is channel-interleaved (i.e. channel0_sample0,
  11.182 + *   channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  11.183 + *   Again, the samples need not be block-aligned but they must be
  11.184 + *   sample-aligned, i.e. the first value should be channel0_sample0 and
  11.185 + *   the last value channelN_sampleM.
  11.186 + *
  11.187 + * Note that for either process call, each sample in the buffers should be a
  11.188 + * signed integer, right-justified to the resolution set by
  11.189 + * FLAC__stream_encoder_set_bits_per_sample().  For example, if the resolution
  11.190 + * is 16 bits per sample, the samples should all be in the range [-32768,32767].
  11.191 + *
  11.192 + * When the client is finished encoding data, it calls
  11.193 + * FLAC__stream_encoder_finish(), which causes the encoder to encode any
  11.194 + * data still in its input pipe, and call the metadata callback with the
  11.195 + * final encoding statistics.  Then the instance may be deleted with
  11.196 + * FLAC__stream_encoder_delete() or initialized again to encode another
  11.197 + * stream.
  11.198 + *
  11.199 + * For programs that write their own metadata, but that do not know the
  11.200 + * actual metadata until after encoding, it is advantageous to instruct
  11.201 + * the encoder to write a PADDING block of the correct size, so that
  11.202 + * instead of rewriting the whole stream after encoding, the program can
  11.203 + * just overwrite the PADDING block.  If only the maximum size of the
  11.204 + * metadata is known, the program can write a slightly larger padding
  11.205 + * block, then split it after encoding.
  11.206 + *
  11.207 + * Make sure you understand how lengths are calculated.  All FLAC metadata
  11.208 + * blocks have a 4 byte header which contains the type and length.  This
  11.209 + * length does not include the 4 bytes of the header.  See the format page
  11.210 + * for the specification of metadata blocks and their lengths.
  11.211 + *
  11.212 + * \note
  11.213 + * If you are writing the FLAC data to a file via callbacks, make sure it
  11.214 + * is open for update (e.g. mode "w+" for stdio streams).  This is because
  11.215 + * after the first encoding pass, the encoder will try to seek back to the
  11.216 + * beginning of the stream, to the STREAMINFO block, to write some data
  11.217 + * there.  (If using FLAC__stream_encoder_init*_file() or
  11.218 + * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
  11.219 + *
  11.220 + * \note
  11.221 + * The "set" functions may only be called when the encoder is in the
  11.222 + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
  11.223 + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
  11.224 + * before FLAC__stream_encoder_init_*().  If this is the case they will
  11.225 + * return \c true, otherwise \c false.
  11.226 + *
  11.227 + * \note
  11.228 + * FLAC__stream_encoder_finish() resets all settings to the constructor
  11.229 + * defaults.
  11.230 + *
  11.231 + * \{
  11.232 + */
  11.233 +
  11.234 +
  11.235 +/** State values for a FLAC__StreamEncoder.
  11.236 + *
  11.237 + * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
  11.238 + *
  11.239 + * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
  11.240 + * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
  11.241 + * must be deleted with FLAC__stream_encoder_delete().
  11.242 + */
  11.243 +typedef enum {
  11.244 +
  11.245 +	FLAC__STREAM_ENCODER_OK = 0,
  11.246 +	/**< The encoder is in the normal OK state and samples can be processed. */
  11.247 +
  11.248 +	FLAC__STREAM_ENCODER_UNINITIALIZED,
  11.249 +	/**< The encoder is in the uninitialized state; one of the
  11.250 +	 * FLAC__stream_encoder_init_*() functions must be called before samples
  11.251 +	 * can be processed.
  11.252 +	 */
  11.253 +
  11.254 +	FLAC__STREAM_ENCODER_OGG_ERROR,
  11.255 +	/**< An error occurred in the underlying Ogg layer.  */
  11.256 +
  11.257 +	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
  11.258 +	/**< An error occurred in the underlying verify stream decoder;
  11.259 +	 * check FLAC__stream_encoder_get_verify_decoder_state().
  11.260 +	 */
  11.261 +
  11.262 +	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
  11.263 +	/**< The verify decoder detected a mismatch between the original
  11.264 +	 * audio signal and the decoded audio signal.
  11.265 +	 */
  11.266 +
  11.267 +	FLAC__STREAM_ENCODER_CLIENT_ERROR,
  11.268 +	/**< One of the callbacks returned a fatal error. */
  11.269 +
  11.270 +	FLAC__STREAM_ENCODER_IO_ERROR,
  11.271 +	/**< An I/O error occurred while opening/reading/writing a file.
  11.272 +	 * Check \c errno.
  11.273 +	 */
  11.274 +
  11.275 +	FLAC__STREAM_ENCODER_FRAMING_ERROR,
  11.276 +	/**< An error occurred while writing the stream; usually, the
  11.277 +	 * write_callback returned an error.
  11.278 +	 */
  11.279 +
  11.280 +	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
  11.281 +	/**< Memory allocation failed. */
  11.282 +
  11.283 +} FLAC__StreamEncoderState;
  11.284 +
  11.285 +/** Maps a FLAC__StreamEncoderState to a C string.
  11.286 + *
  11.287 + *  Using a FLAC__StreamEncoderState as the index to this array
  11.288 + *  will give the string equivalent.  The contents should not be modified.
  11.289 + */
  11.290 +extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
  11.291 +
  11.292 +
  11.293 +/** Possible return values for the FLAC__stream_encoder_init_*() functions.
  11.294 + */
  11.295 +typedef enum {
  11.296 +
  11.297 +	FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
  11.298 +	/**< Initialization was successful. */
  11.299 +
  11.300 +	FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
  11.301 +	/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
  11.302 +
  11.303 +	FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  11.304 +	/**< The library was not compiled with support for the given container
  11.305 +	 * format.
  11.306 +	 */
  11.307 +
  11.308 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
  11.309 +	/**< A required callback was not supplied. */
  11.310 +
  11.311 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
  11.312 +	/**< The encoder has an invalid setting for number of channels. */
  11.313 +
  11.314 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
  11.315 +	/**< The encoder has an invalid setting for bits-per-sample.
  11.316 +	 * FLAC supports 4-32 bps but the reference encoder currently supports
  11.317 +	 * only up to 24 bps.
  11.318 +	 */
  11.319 +
  11.320 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
  11.321 +	/**< The encoder has an invalid setting for the input sample rate. */
  11.322 +
  11.323 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
  11.324 +	/**< The encoder has an invalid setting for the block size. */
  11.325 +
  11.326 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
  11.327 +	/**< The encoder has an invalid setting for the maximum LPC order. */
  11.328 +
  11.329 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
  11.330 +	/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
  11.331 +
  11.332 +	FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
  11.333 +	/**< The specified block size is less than the maximum LPC order. */
  11.334 +
  11.335 +	FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
  11.336 +	/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
  11.337 +
  11.338 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
  11.339 +	/**< The metadata input to the encoder is invalid, in one of the following ways:
  11.340 +	 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
  11.341 +	 * - One of the metadata blocks contains an undefined type
  11.342 +	 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
  11.343 +	 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
  11.344 +	 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
  11.345 +	 */
  11.346 +
  11.347 +	FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
  11.348 +	/**< FLAC__stream_encoder_init_*() was called when the encoder was
  11.349 +	 * already initialized, usually because
  11.350 +	 * FLAC__stream_encoder_finish() was not called.
  11.351 +	 */
  11.352 +
  11.353 +} FLAC__StreamEncoderInitStatus;
  11.354 +
  11.355 +/** Maps a FLAC__StreamEncoderInitStatus to a C string.
  11.356 + *
  11.357 + *  Using a FLAC__StreamEncoderInitStatus as the index to this array
  11.358 + *  will give the string equivalent.  The contents should not be modified.
  11.359 + */
  11.360 +extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
  11.361 +
  11.362 +
  11.363 +/** Return values for the FLAC__StreamEncoder read callback.
  11.364 + */
  11.365 +typedef enum {
  11.366 +
  11.367 +	FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
  11.368 +	/**< The read was OK and decoding can continue. */
  11.369 +
  11.370 +	FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
  11.371 +	/**< The read was attempted at the end of the stream. */
  11.372 +
  11.373 +	FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
  11.374 +	/**< An unrecoverable error occurred. */
  11.375 +
  11.376 +	FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
  11.377 +	/**< Client does not support reading back from the output. */
  11.378 +
  11.379 +} FLAC__StreamEncoderReadStatus;
  11.380 +
  11.381 +/** Maps a FLAC__StreamEncoderReadStatus to a C string.
  11.382 + *
  11.383 + *  Using a FLAC__StreamEncoderReadStatus as the index to this array
  11.384 + *  will give the string equivalent.  The contents should not be modified.
  11.385 + */
  11.386 +extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
  11.387 +
  11.388 +
  11.389 +/** Return values for the FLAC__StreamEncoder write callback.
  11.390 + */
  11.391 +typedef enum {
  11.392 +
  11.393 +	FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
  11.394 +	/**< The write was OK and encoding can continue. */
  11.395 +
  11.396 +	FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
  11.397 +	/**< An unrecoverable error occurred.  The encoder will return from the process call. */
  11.398 +
  11.399 +} FLAC__StreamEncoderWriteStatus;
  11.400 +
  11.401 +/** Maps a FLAC__StreamEncoderWriteStatus to a C string.
  11.402 + *
  11.403 + *  Using a FLAC__StreamEncoderWriteStatus as the index to this array
  11.404 + *  will give the string equivalent.  The contents should not be modified.
  11.405 + */
  11.406 +extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
  11.407 +
  11.408 +
  11.409 +/** Return values for the FLAC__StreamEncoder seek callback.
  11.410 + */
  11.411 +typedef enum {
  11.412 +
  11.413 +	FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
  11.414 +	/**< The seek was OK and encoding can continue. */
  11.415 +
  11.416 +	FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
  11.417 +	/**< An unrecoverable error occurred. */
  11.418 +
  11.419 +	FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  11.420 +	/**< Client does not support seeking. */
  11.421 +
  11.422 +} FLAC__StreamEncoderSeekStatus;
  11.423 +
  11.424 +/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
  11.425 + *
  11.426 + *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
  11.427 + *  will give the string equivalent.  The contents should not be modified.
  11.428 + */
  11.429 +extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
  11.430 +
  11.431 +
  11.432 +/** Return values for the FLAC__StreamEncoder tell callback.
  11.433 + */
  11.434 +typedef enum {
  11.435 +
  11.436 +	FLAC__STREAM_ENCODER_TELL_STATUS_OK,
  11.437 +	/**< The tell was OK and encoding can continue. */
  11.438 +
  11.439 +	FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
  11.440 +	/**< An unrecoverable error occurred. */
  11.441 +
  11.442 +	FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  11.443 +	/**< Client does not support seeking. */
  11.444 +
  11.445 +} FLAC__StreamEncoderTellStatus;
  11.446 +
  11.447 +/** Maps a FLAC__StreamEncoderTellStatus to a C string.
  11.448 + *
  11.449 + *  Using a FLAC__StreamEncoderTellStatus as the index to this array
  11.450 + *  will give the string equivalent.  The contents should not be modified.
  11.451 + */
  11.452 +extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
  11.453 +
  11.454 +
  11.455 +/***********************************************************************
  11.456 + *
  11.457 + * class FLAC__StreamEncoder
  11.458 + *
  11.459 + ***********************************************************************/
  11.460 +
  11.461 +struct FLAC__StreamEncoderProtected;
  11.462 +struct FLAC__StreamEncoderPrivate;
  11.463 +/** The opaque structure definition for the stream encoder type.
  11.464 + *  See the \link flac_stream_encoder stream encoder module \endlink
  11.465 + *  for a detailed description.
  11.466 + */
  11.467 +typedef struct {
  11.468 +	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  11.469 +	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
  11.470 +} FLAC__StreamEncoder;
  11.471 +
  11.472 +/** Signature for the read callback.
  11.473 + *
  11.474 + *  A function pointer matching this signature must be passed to
  11.475 + *  FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
  11.476 + *  The supplied function will be called when the encoder needs to read back
  11.477 + *  encoded data.  This happens during the metadata callback, when the encoder
  11.478 + *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
  11.479 + *  while encoding.  The address of the buffer to be filled is supplied, along
  11.480 + *  with the number of bytes the buffer can hold.  The callback may choose to
  11.481 + *  supply less data and modify the byte count but must be careful not to
  11.482 + *  overflow the buffer.  The callback then returns a status code chosen from
  11.483 + *  FLAC__StreamEncoderReadStatus.
  11.484 + *
  11.485 + * Here is an example of a read callback for stdio streams:
  11.486 + * \code
  11.487 + * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  11.488 + * {
  11.489 + *   FILE *file = ((MyClientData*)client_data)->file;
  11.490 + *   if(*bytes > 0) {
  11.491 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  11.492 + *     if(ferror(file))
  11.493 + *       return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  11.494 + *     else if(*bytes == 0)
  11.495 + *       return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
  11.496 + *     else
  11.497 + *       return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
  11.498 + *   }
  11.499 + *   else
  11.500 + *     return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  11.501 + * }
  11.502 + * \endcode
  11.503 + *
  11.504 + * \note In general, FLAC__StreamEncoder functions which change the
  11.505 + * state should not be called on the \a encoder while in the callback.
  11.506 + *
  11.507 + * \param  encoder  The encoder instance calling the callback.
  11.508 + * \param  buffer   A pointer to a location for the callee to store
  11.509 + *                  data to be encoded.
  11.510 + * \param  bytes    A pointer to the size of the buffer.  On entry
  11.511 + *                  to the callback, it contains the maximum number
  11.512 + *                  of bytes that may be stored in \a buffer.  The
  11.513 + *                  callee must set it to the actual number of bytes
  11.514 + *                  stored (0 in case of error or end-of-stream) before
  11.515 + *                  returning.
  11.516 + * \param  client_data  The callee's client data set through
  11.517 + *                      FLAC__stream_encoder_set_client_data().
  11.518 + * \retval FLAC__StreamEncoderReadStatus
  11.519 + *    The callee's return status.
  11.520 + */
  11.521 +typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  11.522 +
  11.523 +/** Signature for the write callback.
  11.524 + *
  11.525 + *  A function pointer matching this signature must be passed to
  11.526 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  11.527 + *  by the encoder anytime there is raw encoded data ready to write.  It may
  11.528 + *  include metadata mixed with encoded audio frames and the data is not
  11.529 + *  guaranteed to be aligned on frame or metadata block boundaries.
  11.530 + *
  11.531 + *  The only duty of the callback is to write out the \a bytes worth of data
  11.532 + *  in \a buffer to the current position in the output stream.  The arguments
  11.533 + *  \a samples and \a current_frame are purely informational.  If \a samples
  11.534 + *  is greater than \c 0, then \a current_frame will hold the current frame
  11.535 + *  number that is being written; otherwise it indicates that the write
  11.536 + *  callback is being called to write metadata.
  11.537 + *
  11.538 + * \note
  11.539 + * Unlike when writing to native FLAC, when writing to Ogg FLAC the
  11.540 + * write callback will be called twice when writing each audio
  11.541 + * frame; once for the page header, and once for the page body.
  11.542 + * When writing the page header, the \a samples argument to the
  11.543 + * write callback will be \c 0.
  11.544 + *
  11.545 + * \note In general, FLAC__StreamEncoder functions which change the
  11.546 + * state should not be called on the \a encoder while in the callback.
  11.547 + *
  11.548 + * \param  encoder  The encoder instance calling the callback.
  11.549 + * \param  buffer   An array of encoded data of length \a bytes.
  11.550 + * \param  bytes    The byte length of \a buffer.
  11.551 + * \param  samples  The number of samples encoded by \a buffer.
  11.552 + *                  \c 0 has a special meaning; see above.
  11.553 + * \param  current_frame  The number of the current frame being encoded.
  11.554 + * \param  client_data  The callee's client data set through
  11.555 + *                      FLAC__stream_encoder_init_*().
  11.556 + * \retval FLAC__StreamEncoderWriteStatus
  11.557 + *    The callee's return status.
  11.558 + */
  11.559 +typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data);
  11.560 +
  11.561 +/** Signature for the seek callback.
  11.562 + *
  11.563 + *  A function pointer matching this signature may be passed to
  11.564 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  11.565 + *  when the encoder needs to seek the output stream.  The encoder will pass
  11.566 + *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
  11.567 + *
  11.568 + * Here is an example of a seek callback for stdio streams:
  11.569 + * \code
  11.570 + * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  11.571 + * {
  11.572 + *   FILE *file = ((MyClientData*)client_data)->file;
  11.573 + *   if(file == stdin)
  11.574 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
  11.575 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  11.576 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
  11.577 + *   else
  11.578 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
  11.579 + * }
  11.580 + * \endcode
  11.581 + *
  11.582 + * \note In general, FLAC__StreamEncoder functions which change the
  11.583 + * state should not be called on the \a encoder while in the callback.
  11.584 + *
  11.585 + * \param  encoder  The encoder instance calling the callback.
  11.586 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  11.587 + *                               to seek to.
  11.588 + * \param  client_data  The callee's client data set through
  11.589 + *                      FLAC__stream_encoder_init_*().
  11.590 + * \retval FLAC__StreamEncoderSeekStatus
  11.591 + *    The callee's return status.
  11.592 + */
  11.593 +typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  11.594 +
  11.595 +/** Signature for the tell callback.
  11.596 + *
  11.597 + *  A function pointer matching this signature may be passed to
  11.598 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  11.599 + *  when the encoder needs to know the current position of the output stream.
  11.600 + *
  11.601 + * \warning
  11.602 + * The callback must return the true current byte offset of the output to
  11.603 + * which the encoder is writing.  If you are buffering the output, make
  11.604 + * sure and take this into account.  If you are writing directly to a
  11.605 + * FILE* from your write callback, ftell() is sufficient.  If you are
  11.606 + * writing directly to a file descriptor from your write callback, you
  11.607 + * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
  11.608 + * these points to rewrite metadata after encoding.
  11.609 + *
  11.610 + * Here is an example of a tell callback for stdio streams:
  11.611 + * \code
  11.612 + * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  11.613 + * {
  11.614 + *   FILE *file = ((MyClientData*)client_data)->file;
  11.615 + *   off_t pos;
  11.616 + *   if(file == stdin)
  11.617 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
  11.618 + *   else if((pos = ftello(file)) < 0)
  11.619 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
  11.620 + *   else {
  11.621 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  11.622 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
  11.623 + *   }
  11.624 + * }
  11.625 + * \endcode
  11.626 + *
  11.627 + * \note In general, FLAC__StreamEncoder functions which change the
  11.628 + * state should not be called on the \a encoder while in the callback.
  11.629 + *
  11.630 + * \param  encoder  The encoder instance calling the callback.
  11.631 + * \param  absolute_byte_offset  The address at which to store the current
  11.632 + *                               position of the output.
  11.633 + * \param  client_data  The callee's client data set through
  11.634 + *                      FLAC__stream_encoder_init_*().
  11.635 + * \retval FLAC__StreamEncoderTellStatus
  11.636 + *    The callee's return status.
  11.637 + */
  11.638 +typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  11.639 +
  11.640 +/** Signature for the metadata callback.
  11.641 + *
  11.642 + *  A function pointer matching this signature may be passed to
  11.643 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  11.644 + *  once at the end of encoding with the populated STREAMINFO structure.  This
  11.645 + *  is so the client can seek back to the beginning of the file and write the
  11.646 + *  STREAMINFO block with the correct statistics after encoding (like
  11.647 + *  minimum/maximum frame size and total samples).
  11.648 + *
  11.649 + * \note In general, FLAC__StreamEncoder functions which change the
  11.650 + * state should not be called on the \a encoder while in the callback.
  11.651 + *
  11.652 + * \param  encoder      The encoder instance calling the callback.
  11.653 + * \param  metadata     The final populated STREAMINFO block.
  11.654 + * \param  client_data  The callee's client data set through
  11.655 + *                      FLAC__stream_encoder_init_*().
  11.656 + */
  11.657 +typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
  11.658 +
  11.659 +/** Signature for the progress callback.
  11.660 + *
  11.661 + *  A function pointer matching this signature may be passed to
  11.662 + *  FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
  11.663 + *  The supplied function will be called when the encoder has finished
  11.664 + *  writing a frame.  The \c total_frames_estimate argument to the
  11.665 + *  callback will be based on the value from
  11.666 + *  FLAC__stream_encoder_set_total_samples_estimate().
  11.667 + *
  11.668 + * \note In general, FLAC__StreamEncoder functions which change the
  11.669 + * state should not be called on the \a encoder while in the callback.
  11.670 + *
  11.671 + * \param  encoder          The encoder instance calling the callback.
  11.672 + * \param  bytes_written    Bytes written so far.
  11.673 + * \param  samples_written  Samples written so far.
  11.674 + * \param  frames_written   Frames written so far.
  11.675 + * \param  total_frames_estimate  The estimate of the total number of
  11.676 + *                                frames to be written.
  11.677 + * \param  client_data      The callee's client data set through
  11.678 + *                          FLAC__stream_encoder_init_*().
  11.679 + */
  11.680 +typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
  11.681 +
  11.682 +
  11.683 +/***********************************************************************
  11.684 + *
  11.685 + * Class constructor/destructor
  11.686 + *
  11.687 + ***********************************************************************/
  11.688 +
  11.689 +/** Create a new stream encoder instance.  The instance is created with
  11.690 + *  default settings; see the individual FLAC__stream_encoder_set_*()
  11.691 + *  functions for each setting's default.
  11.692 + *
  11.693 + * \retval FLAC__StreamEncoder*
  11.694 + *    \c NULL if there was an error allocating memory, else the new instance.
  11.695 + */
  11.696 +FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
  11.697 +
  11.698 +/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
  11.699 + *
  11.700 + * \param encoder  A pointer to an existing encoder.
  11.701 + * \assert
  11.702 + *    \code encoder != NULL \endcode
  11.703 + */
  11.704 +FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  11.705 +
  11.706 +
  11.707 +/***********************************************************************
  11.708 + *
  11.709 + * Public class method prototypes
  11.710 + *
  11.711 + ***********************************************************************/
  11.712 +
  11.713 +/** Set the serial number for the FLAC stream to use in the Ogg container.
  11.714 + *
  11.715 + * \note
  11.716 + * This does not need to be set for native FLAC encoding.
  11.717 + *
  11.718 + * \note
  11.719 + * It is recommended to set a serial number explicitly as the default of '0'
  11.720 + * may collide with other streams.
  11.721 + *
  11.722 + * \default \c 0
  11.723 + * \param  encoder        An encoder instance to set.
  11.724 + * \param  serial_number  See above.
  11.725 + * \assert
  11.726 + *    \code encoder != NULL \endcode
  11.727 + * \retval FLAC__bool
  11.728 + *    \c false if the encoder is already initialized, else \c true.
  11.729 + */
  11.730 +FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
  11.731 +
  11.732 +/** Set the "verify" flag.  If \c true, the encoder will verify it's own
  11.733 + *  encoded output by feeding it through an internal decoder and comparing
  11.734 + *  the original signal against the decoded signal.  If a mismatch occurs,
  11.735 + *  the process call will return \c false.  Note that this will slow the
  11.736 + *  encoding process by the extra time required for decoding and comparison.
  11.737 + *
  11.738 + * \default \c false
  11.739 + * \param  encoder  An encoder instance to set.
  11.740 + * \param  value    Flag value (see above).
  11.741 + * \assert
  11.742 + *    \code encoder != NULL \endcode
  11.743 + * \retval FLAC__bool
  11.744 + *    \c false if the encoder is already initialized, else \c true.
  11.745 + */
  11.746 +FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
  11.747 +
  11.748 +/** Set the <A HREF="../format.html#subset">Subset</A> flag.  If \c true,
  11.749 + *  the encoder will comply with the Subset and will check the
  11.750 + *  settings during FLAC__stream_encoder_init_*() to see if all settings
  11.751 + *  comply.  If \c false, the settings may take advantage of the full
  11.752 + *  range that the format allows.
  11.753 + *
  11.754 + *  Make sure you know what it entails before setting this to \c false.
  11.755 + *
  11.756 + * \default \c true
  11.757 + * \param  encoder  An encoder instance to set.
  11.758 + * \param  value    Flag value (see above).
  11.759 + * \assert
  11.760 + *    \code encoder != NULL \endcode
  11.761 + * \retval FLAC__bool
  11.762 + *    \c false if the encoder is already initialized, else \c true.
  11.763 + */
  11.764 +FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
  11.765 +
  11.766 +/** Set the number of channels to be encoded.
  11.767 + *
  11.768 + * \default \c 2
  11.769 + * \param  encoder  An encoder instance to set.
  11.770 + * \param  value    See above.
  11.771 + * \assert
  11.772 + *    \code encoder != NULL \endcode
  11.773 + * \retval FLAC__bool
  11.774 + *    \c false if the encoder is already initialized, else \c true.
  11.775 + */
  11.776 +FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
  11.777 +
  11.778 +/** Set the sample resolution of the input to be encoded.
  11.779 + *
  11.780 + * \warning
  11.781 + * Do not feed the encoder data that is wider than the value you
  11.782 + * set here or you will generate an invalid stream.
  11.783 + *
  11.784 + * \default \c 16
  11.785 + * \param  encoder  An encoder instance to set.
  11.786 + * \param  value    See above.
  11.787 + * \assert
  11.788 + *    \code encoder != NULL \endcode
  11.789 + * \retval FLAC__bool
  11.790 + *    \c false if the encoder is already initialized, else \c true.
  11.791 + */
  11.792 +FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
  11.793 +
  11.794 +/** Set the sample rate (in Hz) of the input to be encoded.
  11.795 + *
  11.796 + * \default \c 44100
  11.797 + * \param  encoder  An encoder instance to set.
  11.798 + * \param  value    See above.
  11.799 + * \assert
  11.800 + *    \code encoder != NULL \endcode
  11.801 + * \retval FLAC__bool
  11.802 + *    \c false if the encoder is already initialized, else \c true.
  11.803 + */
  11.804 +FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
  11.805 +
  11.806 +/** Set the compression level
  11.807 + *
  11.808 + * The compression level is roughly proportional to the amount of effort
  11.809 + * the encoder expends to compress the file.  A higher level usually
  11.810 + * means more computation but higher compression.  The default level is
  11.811 + * suitable for most applications.
  11.812 + *
  11.813 + * Currently the levels range from \c 0 (fastest, least compression) to
  11.814 + * \c 8 (slowest, most compression).  A value larger than \c 8 will be
  11.815 + * treated as \c 8.
  11.816 + *
  11.817 + * This function automatically calls the following other \c _set_
  11.818 + * functions with appropriate values, so the client does not need to
  11.819 + * unless it specifically wants to override them:
  11.820 + * - FLAC__stream_encoder_set_do_mid_side_stereo()
  11.821 + * - FLAC__stream_encoder_set_loose_mid_side_stereo()
  11.822 + * - FLAC__stream_encoder_set_apodization()
  11.823 + * - FLAC__stream_encoder_set_max_lpc_order()
  11.824 + * - FLAC__stream_encoder_set_qlp_coeff_precision()
  11.825 + * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
  11.826 + * - FLAC__stream_encoder_set_do_escape_coding()
  11.827 + * - FLAC__stream_encoder_set_do_exhaustive_model_search()
  11.828 + * - FLAC__stream_encoder_set_min_residual_partition_order()
  11.829 + * - FLAC__stream_encoder_set_max_residual_partition_order()
  11.830 + * - FLAC__stream_encoder_set_rice_parameter_search_dist()
  11.831 + *
  11.832 + * The actual values set for each level are:
  11.833 + * <table>
  11.834 + * <tr>
  11.835 + *  <td><b>level</b><td>
  11.836 + *  <td>do mid-side stereo<td>
  11.837 + *  <td>loose mid-side stereo<td>
  11.838 + *  <td>apodization<td>
  11.839 + *  <td>max lpc order<td>
  11.840 + *  <td>qlp coeff precision<td>
  11.841 + *  <td>qlp coeff prec search<td>
  11.842 + *  <td>escape coding<td>
  11.843 + *  <td>exhaustive model search<td>
  11.844 + *  <td>min residual partition order<td>
  11.845 + *  <td>max residual partition order<td>
  11.846 + *  <td>rice parameter search dist<td>
  11.847 + * </tr>
  11.848 + * <tr>  <td><b>0</b><td>  <td>false<td>  <td>false<td>  <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  11.849 + * <tr>  <td><b>1</b><td>  <td>true<td>   <td>true<td>   <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  11.850 + * <tr>  <td><b>2</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>0<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>3<td>  <td>0<td>  </tr>
  11.851 + * <tr>  <td><b>3</b><td>  <td>false<td>  <td>false<td>  <td>tukey(0.5)<td>  <td>6<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>4<td>  <td>0<td>  </tr>
  11.852 + * <tr>  <td><b>4</b><td>  <td>true<td>   <td>true<td>   <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>4<td>  <td>0<td>  </tr>
  11.853 + * <tr>  <td><b>5</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>5<td>  <td>0<td>  </tr>
  11.854 + * <tr>  <td><b>6</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>false<td>  <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  11.855 + * <tr>  <td><b>7</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>8<td>   <td>0<td>  <td>false<td>  <td>false<td>  <td>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  11.856 + * <tr>  <td><b>8</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>12<td>  <td>0<td>  <td>false<td>  <td>false<td>  <td>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
  11.857 + * </table>
  11.858 + *
  11.859 + * \default \c 5
  11.860 + * \param  encoder  An encoder instance to set.
  11.861 + * \param  value    See above.
  11.862 + * \assert
  11.863 + *    \code encoder != NULL \endcode
  11.864 + * \retval FLAC__bool
  11.865 + *    \c false if the encoder is already initialized, else \c true.
  11.866 + */
  11.867 +FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
  11.868 +
  11.869 +/** Set the blocksize to use while encoding.
  11.870 + *
  11.871 + * The number of samples to use per frame.  Use \c 0 to let the encoder
  11.872 + * estimate a blocksize; this is usually best.
  11.873 + *
  11.874 + * \default \c 0
  11.875 + * \param  encoder  An encoder instance to set.
  11.876 + * \param  value    See above.
  11.877 + * \assert
  11.878 + *    \code encoder != NULL \endcode
  11.879 + * \retval FLAC__bool
  11.880 + *    \c false if the encoder is already initialized, else \c true.
  11.881 + */
  11.882 +FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
  11.883 +
  11.884 +/** Set to \c true to enable mid-side encoding on stereo input.  The
  11.885 + *  number of channels must be 2 for this to have any effect.  Set to
  11.886 + *  \c false to use only independent channel coding.
  11.887 + *
  11.888 + * \default \c false
  11.889 + * \param  encoder  An encoder instance to set.
  11.890 + * \param  value    Flag value (see above).
  11.891 + * \assert
  11.892 + *    \code encoder != NULL \endcode
  11.893 + * \retval FLAC__bool
  11.894 + *    \c false if the encoder is already initialized, else \c true.
  11.895 + */
  11.896 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  11.897 +
  11.898 +/** Set to \c true to enable adaptive switching between mid-side and
  11.899 + *  left-right encoding on stereo input.  Set to \c false to use
  11.900 + *  exhaustive searching.  Setting this to \c true requires
  11.901 + *  FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
  11.902 + *  \c true in order to have any effect.
  11.903 + *
  11.904 + * \default \c false
  11.905 + * \param  encoder  An encoder instance to set.
  11.906 + * \param  value    Flag value (see above).
  11.907 + * \assert
  11.908 + *    \code encoder != NULL \endcode
  11.909 + * \retval FLAC__bool
  11.910 + *    \c false if the encoder is already initialized, else \c true.
  11.911 + */
  11.912 +FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  11.913 +
  11.914 +/** Sets the apodization function(s) the encoder will use when windowing
  11.915 + *  audio data for LPC analysis.
  11.916 + *
  11.917 + * The \a specification is a plain ASCII string which specifies exactly
  11.918 + * which functions to use.  There may be more than one (up to 32),
  11.919 + * separated by \c ';' characters.  Some functions take one or more
  11.920 + * comma-separated arguments in parentheses.
  11.921 + *
  11.922 + * The available functions are \c bartlett, \c bartlett_hann,
  11.923 + * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
  11.924 + * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
  11.925 + * \c rectangle, \c triangle, \c tukey(P), \c welch.
  11.926 + *
  11.927 + * For \c gauss(STDDEV), STDDEV specifies the standard deviation
  11.928 + * (0<STDDEV<=0.5).
  11.929 + *
  11.930 + * For \c tukey(P), P specifies the fraction of the window that is
  11.931 + * tapered (0<=P<=1).  P=0 corresponds to \c rectangle and P=1
  11.932 + * corresponds to \c hann.
  11.933 + *
  11.934 + * Example specifications are \c "blackman" or
  11.935 + * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
  11.936 + *
  11.937 + * Any function that is specified erroneously is silently dropped.  Up
  11.938 + * to 32 functions are kept, the rest are dropped.  If the specification
  11.939 + * is empty the encoder defaults to \c "tukey(0.5)".
  11.940 + *
  11.941 + * When more than one function is specified, then for every subframe the
  11.942 + * encoder will try each of them separately and choose the window that
  11.943 + * results in the smallest compressed subframe.
  11.944 + *
  11.945 + * Note that each function specified causes the encoder to occupy a
  11.946 + * floating point array in which to store the window.
  11.947 + *
  11.948 + * \default \c "tukey(0.5)"
  11.949 + * \param  encoder        An encoder instance to set.
  11.950 + * \param  specification  See above.
  11.951 + * \assert
  11.952 + *    \code encoder != NULL \endcode
  11.953 + *    \code specification != NULL \endcode
  11.954 + * \retval FLAC__bool
  11.955 + *    \c false if the encoder is already initialized, else \c true.
  11.956 + */
  11.957 +FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
  11.958 +
  11.959 +/** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
  11.960 + *
  11.961 + * \default \c 0
  11.962 + * \param  encoder  An encoder instance to set.
  11.963 + * \param  value    See above.
  11.964 + * \assert
  11.965 + *    \code encoder != NULL \endcode
  11.966 + * \retval FLAC__bool
  11.967 + *    \c false if the encoder is already initialized, else \c true.
  11.968 + */
  11.969 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
  11.970 +
  11.971 +/** Set the precision, in bits, of the quantized linear predictor
  11.972 + *  coefficients, or \c 0 to let the encoder select it based on the
  11.973 + *  blocksize.
  11.974 + *
  11.975 + * \note
  11.976 + * In the current implementation, qlp_coeff_precision + bits_per_sample must
  11.977 + * be less than 32.
  11.978 + *
  11.979 + * \default \c 0
  11.980 + * \param  encoder  An encoder instance to set.
  11.981 + * \param  value    See above.
  11.982 + * \assert
  11.983 + *    \code encoder != NULL \endcode
  11.984 + * \retval FLAC__bool
  11.985 + *    \c false if the encoder is already initialized, else \c true.
  11.986 + */
  11.987 +FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
  11.988 +
  11.989 +/** Set to \c false to use only the specified quantized linear predictor
  11.990 + *  coefficient precision, or \c true to search neighboring precision
  11.991 + *  values and use the best one.
  11.992 + *
  11.993 + * \default \c false
  11.994 + * \param  encoder  An encoder instance to set.
  11.995 + * \param  value    See above.
  11.996 + * \assert
  11.997 + *    \code encoder != NULL \endcode
  11.998 + * \retval FLAC__bool
  11.999 + *    \c false if the encoder is already initialized, else \c true.
 11.1000 + */
 11.1001 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
 11.1002 +
 11.1003 +/** Deprecated.  Setting this value has no effect.
 11.1004 + *
 11.1005 + * \default \c false
 11.1006 + * \param  encoder  An encoder instance to set.
 11.1007 + * \param  value    See above.
 11.1008 + * \assert
 11.1009 + *    \code encoder != NULL \endcode
 11.1010 + * \retval FLAC__bool
 11.1011 + *    \c false if the encoder is already initialized, else \c true.