Updated the Windows build to:
authorSam Lantinga <slouken@libsdl.org>
Sun, 01 Jan 2012 14:40:22 -0500
changeset 532b8e8ae4852b2
parent 531 f9c790738ec3
child 533 f19368c22ebd
Updated the Windows build to:
Visual Studio 2008
flac-1.2.1
libogg-1.3.0
libvorbis-1.3.2

All Windows binaries have been rebuilt with mingw-w32-1.0
VisualC/SDL_mixer.dsp
VisualC/SDL_mixer.dsw
VisualC/SDL_mixer.sln
VisualC/SDL_mixer.vcproj
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/COPYING.FLAC.txt
VisualC/flac/lib/libFLAC-8.dll
VisualC/mikmod/lib/COPYING.mikmod.txt
VisualC/mikmod/lib/mikmod.dll
VisualC/native_midi/native_midi.vcproj
VisualC/playmus/playmus.vcproj
VisualC/playwave/playwave.vcproj
VisualC/smpeg/lib/COPYING.smpeg.txt
VisualC/smpeg/lib/smpeg.dll
VisualC/timidity/timidity.vcproj
VisualC/vorbis/include/codec.h
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/include/vorbisfile.h
VisualC/vorbis/lib/COPYING.ogg-vorbis.txt
VisualC/vorbis/lib/libogg-0.dll
VisualC/vorbis/lib/libvorbis-0.dll
VisualC/vorbis/lib/libvorbisfile-3.dll
fluidsynth.c
fluidsynth.h
mixer.c
     1.1 --- a/VisualC/SDL_mixer.dsp	Sun Jan 01 14:23:22 2012 -0500
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,244 +0,0 @@
     1.4 -# Microsoft Developer Studio Project File - Name="SDL_mixer" - Package Owner=<4>
     1.5 -# Microsoft Developer Studio Generated Build File, Format Version 5.00
     1.6 -# ** DO NOT EDIT **
     1.7 -
     1.8 -# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
     1.9 -
    1.10 -CFG=SDL_mixer - Win32 Debug
    1.11 -!MESSAGE This is not a valid makefile. To build this project using NMAKE,
    1.12 -!MESSAGE use the Export Makefile command and run
    1.13 -!MESSAGE 
    1.14 -!MESSAGE NMAKE /f "SDL_mixer.mak".
    1.15 -!MESSAGE 
    1.16 -!MESSAGE You can specify a configuration when running NMAKE
    1.17 -!MESSAGE by defining the macro CFG on the command line. For example:
    1.18 -!MESSAGE 
    1.19 -!MESSAGE NMAKE /f "SDL_mixer.mak" CFG="SDL_mixer - Win32 Debug"
    1.20 -!MESSAGE 
    1.21 -!MESSAGE Possible choices for configuration are:
    1.22 -!MESSAGE 
    1.23 -!MESSAGE "SDL_mixer - Win32 Release" (based on\
    1.24 - "Win32 (x86) Dynamic-Link Library")
    1.25 -!MESSAGE "SDL_mixer - Win32 Debug" (based on\
    1.26 - "Win32 (x86) Dynamic-Link Library")
    1.27 -!MESSAGE 
    1.28 -
    1.29 -# Begin Project
    1.30 -# PROP Scc_ProjName ""
    1.31 -# PROP Scc_LocalPath ""
    1.32 -CPP=cl.exe
    1.33 -MTL=midl.exe
    1.34 -RSC=rc.exe
    1.35 -
    1.36 -!IF  "$(CFG)" == "SDL_mixer - Win32 Release"
    1.37 -
    1.38 -# PROP BASE Use_MFC 0
    1.39 -# PROP BASE Use_Debug_Libraries 0
    1.40 -# PROP BASE Output_Dir "Release"
    1.41 -# PROP BASE Intermediate_Dir "Release"
    1.42 -# PROP BASE Target_Dir ""
    1.43 -# PROP Use_MFC 0
    1.44 -# PROP Use_Debug_Libraries 0
    1.45 -# PROP Output_Dir "Release"
    1.46 -# PROP Intermediate_Dir "Release"
    1.47 -# PROP Ignore_Export_Lib 0
    1.48 -# PROP Target_Dir ""
    1.49 -# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /YX /FD /c
    1.50 -# ADD CPP /nologo /MD /W3 /GX /O2 /I "..\mikmod" /I "..\timidity" /I "..\native_midi" /I "fluidsynth\include" /I "vorbis\include" /I "smpeg\include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /D "WAV_MUSIC" /D "MOD_MUSIC" /D MOD_DYNAMIC=\"mikmod.dll\" /D "MID_MUSIC" /D "USE_TIMIDITY_MIDI" /D "USE_NATIVE_MIDI" /D "USE_FLUIDSYNTH_MIDI" /D FLUIDSYNTH_DYNAMIC=\"libfluidsynth.dll\" /D "OGG_MUSIC" /D OGG_DYNAMIC=\"libvorbisfile-3.dll\" /D "MP3_MUSIC" /D MP3_DYNAMIC=\"smpeg.dll\" /YX /FD /c
    1.51 -# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /o NUL /win32
    1.52 -# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /o NUL /win32
    1.53 -# ADD BASE RSC /l 0x409 /d "NDEBUG"
    1.54 -# ADD RSC /l 0x409 /d "NDEBUG"
    1.55 -BSC32=bscmake.exe
    1.56 -# ADD BASE BSC32 /nologo
    1.57 -# ADD BSC32 /nologo
    1.58 -LINK32=link.exe
    1.59 -# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /subsystem:windows /dll /machine:I386
    1.60 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib winmm.lib SDL.lib /nologo /subsystem:windows /dll /machine:I386
    1.61 -
    1.62 -!ELSEIF  "$(CFG)" == "SDL_mixer - Win32 Debug"
    1.63 -
    1.64 -# PROP BASE Use_MFC 0
    1.65 -# PROP BASE Use_Debug_Libraries 1
    1.66 -# PROP BASE Output_Dir "Debug"
    1.67 -# PROP BASE Intermediate_Dir "Debug"
    1.68 -# PROP BASE Target_Dir ""
    1.69 -# PROP Use_MFC 0
    1.70 -# PROP Use_Debug_Libraries 1
    1.71 -# PROP Output_Dir "Debug"
    1.72 -# PROP Intermediate_Dir "Debug"
    1.73 -# PROP Ignore_Export_Lib 0
    1.74 -# PROP Target_Dir ""
    1.75 -# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /YX /FD /c
    1.76 -# ADD CPP /nologo /MD /W3 /Gm /GX /Zi /Od /I "..\mikmod" /I "..\timidity" /I "..\native_midi" /I "fluidsynth\include" /I "vorbis\include" /I "smpeg\include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /D "WAV_MUSIC" /D "MOD_MUSIC" /D MOD_DYNAMIC=\"mikmod.dll\" /D MOD_DYNAMIC=\"mikmod.dll\" /D "MID_MUSIC" /D "USE_TIMIDITY_MIDI" /D "USE_NATIVE_MIDI" /D "USE_FLUIDSYNTH_MIDI" /D FLUIDSYNTH_DYNAMIC=\"libfluidsynth.dll\" /D "OGG_MUSIC" /D OGG_DYNAMIC=\"libvorbisfile-3.dll\" /D "MP3_MUSIC" /D MP3_DYNAMIC=\"smpeg.dll\" /YX /FD /c
    1.77 -# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /o NUL /win32
    1.78 -# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /o NUL /win32
    1.79 -# ADD BASE RSC /l 0x409 /d "_DEBUG"
    1.80 -# ADD RSC /l 0x409 /d "_DEBUG"
    1.81 -BSC32=bscmake.exe
    1.82 -# ADD BASE BSC32 /nologo
    1.83 -# ADD BSC32 /nologo
    1.84 -LINK32=link.exe
    1.85 -# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /subsystem:windows /dll /debug /machine:I386 /pdbtype:sept
    1.86 -# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib winmm.lib SDL.lib /nologo /subsystem:windows /dll /debug /machine:I386 /pdbtype:sept
    1.87 -
    1.88 -!ENDIF 
    1.89 -
    1.90 -# Begin Target
    1.91 -
    1.92 -# Name "SDL_mixer - Win32 Release"
    1.93 -# Name "SDL_mixer - Win32 Debug"
    1.94 -# Begin Source File
    1.95 -
    1.96 -SOURCE=..\dynamic_flac.c
    1.97 -# End Source File
    1.98 -# Begin Source File
    1.99 -
   1.100 -SOURCE=..\dynamic_flac.h
   1.101 -# End Source File
   1.102 -# Begin Source File
   1.103 -
   1.104 -SOURCE=..\dynamic_fluidsynth.c
   1.105 -# End Source File
   1.106 -# Begin Source File
   1.107 -
   1.108 -SOURCE=..\dynamic_fluidsynth.h
   1.109 -# End Source File
   1.110 -# Begin Source File
   1.111 -
   1.112 -SOURCE=..\dynamic_mod.c
   1.113 -# End Source File
   1.114 -# Begin Source File
   1.115 -
   1.116 -SOURCE=..\dynamic_mod.h
   1.117 -# End Source File
   1.118 -# Begin Source File
   1.119 -
   1.120 -SOURCE=..\dynamic_mp3.c
   1.121 -# End Source File
   1.122 -# Begin Source File
   1.123 -
   1.124 -SOURCE=..\dynamic_mp3.h
   1.125 -# End Source File
   1.126 -# Begin Source File
   1.127 -
   1.128 -SOURCE=..\dynamic_ogg.c
   1.129 -# End Source File
   1.130 -# Begin Source File
   1.131 -
   1.132 -SOURCE=..\dynamic_ogg.h
   1.133 -# End Source File
   1.134 -# Begin Source File
   1.135 -
   1.136 -SOURCE=..\effect_position.c
   1.137 -# End Source File
   1.138 -# Begin Source File
   1.139 -
   1.140 -SOURCE=..\effect_stereoreverse.c
   1.141 -# End Source File
   1.142 -# Begin Source File
   1.143 -
   1.144 -SOURCE=..\effects_internal.c
   1.145 -# End Source File
   1.146 -# Begin Source File
   1.147 -
   1.148 -SOURCE=..\effects_internal.h
   1.149 -# End Source File
   1.150 -# Begin Source File
   1.151 -
   1.152 -SOURCE=..\fluidsynth.c
   1.153 -# End Source File
   1.154 -# Begin Source File
   1.155 -
   1.156 -SOURCE=..\fluidsynth.h
   1.157 -# End Source File
   1.158 -# Begin Source File
   1.159 -
   1.160 -SOURCE=..\load_aiff.c
   1.161 -# End Source File
   1.162 -# Begin Source File
   1.163 -
   1.164 -SOURCE=..\load_aiff.h
   1.165 -# End Source File
   1.166 -# Begin Source File
   1.167 -
   1.168 -SOURCE=..\load_ogg.c
   1.169 -# End Source File
   1.170 -# Begin Source File
   1.171 -
   1.172 -SOURCE=..\load_ogg.h
   1.173 -# End Source File
   1.174 -# Begin Source File
   1.175 -
   1.176 -SOURCE=..\load_voc.c
   1.177 -# End Source File
   1.178 -# Begin Source File
   1.179 -
   1.180 -SOURCE=..\load_voc.h
   1.181 -# End Source File
   1.182 -# Begin Source File
   1.183 -
   1.184 -SOURCE=..\mixer.c
   1.185 -# End Source File
   1.186 -# Begin Source File
   1.187 -
   1.188 -SOURCE=..\music.c
   1.189 -# End Source File
   1.190 -# Begin Source File
   1.191 -
   1.192 -SOURCE=..\music_cmd.c
   1.193 -# End Source File
   1.194 -# Begin Source File
   1.195 -
   1.196 -SOURCE=..\music_cmd.h
   1.197 -# End Source File
   1.198 -# Begin Source File
   1.199 -
   1.200 -SOURCE=..\music_flac.c
   1.201 -# End Source File
   1.202 -# Begin Source File
   1.203 -
   1.204 -SOURCE=..\music_flac.h
   1.205 -# End Source File
   1.206 -# Begin Source File
   1.207 -
   1.208 -SOURCE=..\music_mad.c
   1.209 -# End Source File
   1.210 -# Begin Source File
   1.211 -
   1.212 -SOURCE=..\music_mad.h
   1.213 -# End Source File
   1.214 -# Begin Source File
   1.215 -
   1.216 -SOURCE=..\music_mod.c
   1.217 -# End Source File
   1.218 -# Begin Source File
   1.219 -
   1.220 -SOURCE=..\music_mod.h
   1.221 -# End Source File
   1.222 -# Begin Source File
   1.223 -
   1.224 -SOURCE=..\music_ogg.c
   1.225 -# End Source File
   1.226 -# Begin Source File
   1.227 -
   1.228 -SOURCE=..\music_ogg.h
   1.229 -# End Source File
   1.230 -# Begin Source File
   1.231 -
   1.232 -SOURCE=..\SDL_mixer.h
   1.233 -# End Source File
   1.234 -# Begin Source File
   1.235 -
   1.236 -SOURCE=..\wavestream.c
   1.237 -# End Source File
   1.238 -# Begin Source File
   1.239 -
   1.240 -SOURCE=..\wavestream.h
   1.241 -# End Source File
   1.242 -# Begin Source File
   1.243 -
   1.244 -SOURCE=Version.rc
   1.245 -# End Source File
   1.246 -# End Target
   1.247 -# End Project
     2.1 --- a/VisualC/SDL_mixer.dsw	Sun Jan 01 14:23:22 2012 -0500
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,83 +0,0 @@
     2.4 -Microsoft Developer Studio Workspace File, Format Version 5.00
     2.5 -# WARNING: DO NOT EDIT OR DELETE THIS WORKSPACE FILE!
     2.6 -
     2.7 -###############################################################################
     2.8 -
     2.9 -Project: "SDL_mixer"=".\SDL_mixer.dsp" - Package Owner=<4>
    2.10 -
    2.11 -Package=<5>
    2.12 -{{{
    2.13 -}}}
    2.14 -
    2.15 -Package=<4>
    2.16 -{{{
    2.17 -    Begin Project Dependency
    2.18 -    Project_Dep_Name timidity
    2.19 -    End Project Dependency
    2.20 -    Begin Project Dependency
    2.21 -    Project_Dep_Name native_midi
    2.22 -    End Project Dependency
    2.23 -}}}
    2.24 -
    2.25 -###############################################################################
    2.26 -
    2.27 -Project: "native_midi"=".\native_midi\native_midi.dsp" - Package Owner=<4>
    2.28 -
    2.29 -Package=<5>
    2.30 -{{{
    2.31 -}}}
    2.32 -
    2.33 -Package=<4>
    2.34 -{{{
    2.35 -}}}
    2.36 -
    2.37 -###############################################################################
    2.38 -
    2.39 -Project: "playmus"=".\playmus\playmus.dsp" - Package Owner=<4>
    2.40 -
    2.41 -Package=<5>
    2.42 -{{{
    2.43 -}}}
    2.44 -
    2.45 -Package=<4>
    2.46 -{{{
    2.47 -}}}
    2.48 -
    2.49 -###############################################################################
    2.50 -
    2.51 -Project: "playwave"=".\playwave\playwave.dsp" - Package Owner=<4>
    2.52 -
    2.53 -Package=<5>
    2.54 -{{{
    2.55 -}}}
    2.56 -
    2.57 -Package=<4>
    2.58 -{{{
    2.59 -}}}
    2.60 -
    2.61 -###############################################################################
    2.62 -
    2.63 -Project: "timidity"=".\timidity\timidity.dsp" - Package Owner=<4>
    2.64 -
    2.65 -Package=<5>
    2.66 -{{{
    2.67 -}}}
    2.68 -
    2.69 -Package=<4>
    2.70 -{{{
    2.71 -}}}
    2.72 -
    2.73 -###############################################################################
    2.74 -
    2.75 -Global:
    2.76 -
    2.77 -Package=<5>
    2.78 -{{{
    2.79 -}}}
    2.80 -
    2.81 -Package=<3>
    2.82 -{{{
    2.83 -}}}
    2.84 -
    2.85 -###############################################################################
    2.86 -
     3.1 --- a/VisualC/SDL_mixer.sln	Sun Jan 01 14:23:22 2012 -0500
     3.2 +++ b/VisualC/SDL_mixer.sln	Sun Jan 01 14:40:22 2012 -0500
     3.3 @@ -1,6 +1,6 @@
     3.4  
     3.5 -Microsoft Visual Studio Solution File, Format Version 9.00
     3.6 -# Visual Studio 2005
     3.7 +Microsoft Visual Studio Solution File, Format Version 10.00
     3.8 +# Visual Studio 2008
     3.9  Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "SDL_mixer", "SDL_mixer.vcproj", "{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}"
    3.10  	ProjectSection(ProjectDependencies) = postProject
    3.11  		{B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C} = {B162B6F1-E876-4D5F-A1F6-E3A6DC2F4A2C}
     4.1 --- a/VisualC/SDL_mixer.vcproj	Sun Jan 01 14:23:22 2012 -0500
     4.2 +++ b/VisualC/SDL_mixer.vcproj	Sun Jan 01 14:40:22 2012 -0500
     4.3 @@ -1,10 +1,11 @@
     4.4  <?xml version="1.0" encoding="Windows-1252"?>
     4.5  <VisualStudioProject
     4.6  	ProjectType="Visual C++"
     4.7 -	Version="8.00"
     4.8 +	Version="9.00"
     4.9  	Name="SDL_mixer"
    4.10  	ProjectGUID="{F7E944B3-0815-40CD-B3E4-90B2A15B0E33}"
    4.11  	RootNamespace="SDL_mixer"
    4.12 +	TargetFrameworkVersion="131072"
    4.13  	>
    4.14  	<Platforms>
    4.15  		<Platform
    4.16 @@ -48,8 +49,8 @@
    4.17  				Name="VCCLCompilerTool"
    4.18  				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
    4.19  				Optimization="0"
    4.20 -				AdditionalIncludeDirectories="..\timidity;..\native_midi;fluidsynth\include;mikmod\include;smpeg\include;vorbis\include"
    4.21 -				PreprocessorDefinitions="_DEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MOD_DYNAMIC=\&quot;mikmod.dll\&quot;;MID_MUSIC;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI;USE_FLUIDSYNTH_MIDI;FLUIDSYNTH_DYNAMIC=\&quot;libfluidsynth.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;"
    4.22 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;flac\include;mikmod\include;smpeg\include;vorbis\include"
    4.23 +				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"
    4.24  				MinimalRebuild="true"
    4.25  				RuntimeLibrary="2"
    4.26  				PrecompiledHeaderFile=".\Debug/SDL_mixer.pch"
    4.27 @@ -80,6 +81,8 @@
    4.28  				GenerateDebugInformation="true"
    4.29  				ProgramDatabaseFile=".\Debug/SDL_mixer.pdb"
    4.30  				SubSystem="2"
    4.31 +				RandomizedBaseAddress="1"
    4.32 +				DataExecutionPrevention="0"
    4.33  				ImportLibrary=".\Debug/SDL_mixer.lib"
    4.34  				TargetMachine="1"
    4.35  			/>
    4.36 @@ -104,9 +107,6 @@
    4.37  				Name="VCAppVerifierTool"
    4.38  			/>
    4.39  			<Tool
    4.40 -				Name="VCWebDeploymentTool"
    4.41 -			/>
    4.42 -			<Tool
    4.43  				Name="VCPostBuildEventTool"
    4.44  			/>
    4.45  		</Configuration>
    4.46 @@ -145,8 +145,8 @@
    4.47  				AdditionalOptions="/D OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;"
    4.48  				Optimization="2"
    4.49  				InlineFunctionExpansion="1"
    4.50 -				AdditionalIncludeDirectories="..\timidity;..\native_midi;fluidsynth/include;mikmod\include;smpeg\include;vorbis\include"
    4.51 -				PreprocessorDefinitions="NDEBUG;WIN32;_WINDOWS;_CRT_SECURE_NO_WARNINGS;WAV_MUSIC;MOD_MUSIC;MID_MUSIC;MOD_DYNAMIC=\&quot;mikmod.dll\&quot;;USE_TIMIDITY_MIDI;USE_NATIVE_MIDI;USE_FLUIDSYNTH_MIDI;FLUIDSYNTH_DYNAMIC=\&quot;libfluidsynth.dll\&quot;;OGG_MUSIC;OGG_DYNAMIC=\&quot;libvorbisfile-3.dll\&quot;;MP3_MUSIC;MP3_DYNAMIC=\&quot;smpeg.dll\&quot;"
    4.52 +				AdditionalIncludeDirectories="..\timidity;..\native_midi;flac\include;mikmod\include;smpeg\include;vorbis\include"
    4.53 +				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"
    4.54  				StringPooling="true"
    4.55  				RuntimeLibrary="2"
    4.56  				EnableFunctionLevelLinking="true"
    4.57 @@ -176,6 +176,8 @@
    4.58  				SuppressStartupBanner="true"
    4.59  				ProgramDatabaseFile=".\Release/SDL_mixer.pdb"
    4.60  				SubSystem="2"
    4.61 +				RandomizedBaseAddress="1"
    4.62 +				DataExecutionPrevention="0"
    4.63  				ImportLibrary=".\Release/SDL_mixer.lib"
    4.64  				TargetMachine="1"
    4.65  			/>
    4.66 @@ -200,9 +202,6 @@
    4.67  				Name="VCAppVerifierTool"
    4.68  			/>
    4.69  			<Tool
    4.70 -				Name="VCWebDeploymentTool"
    4.71 -			/>
    4.72 -			<Tool
    4.73  				Name="VCPostBuildEventTool"
    4.74  			/>
    4.75  		</Configuration>
    4.76 @@ -391,6 +390,14 @@
    4.77  			>
    4.78  		</File>
    4.79  		<File
    4.80 +			RelativePath="..\load_flac.c"
    4.81 +			>
    4.82 +		</File>
    4.83 +		<File
    4.84 +			RelativePath="..\load_flac.h"
    4.85 +			>
    4.86 +		</File>
    4.87 +		<File
    4.88  			RelativePath="..\load_ogg.c"
    4.89  			>
    4.90  			<FileConfiguration
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/VisualC/flac/include/FLAC/all.h	Sun Jan 01 14:40:22 2012 -0500
     5.3 @@ -0,0 +1,370 @@
     5.4 +/* libFLAC - Free Lossless Audio Codec library
     5.5 + * Copyright (C) 2000,2001,2002,2003,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__ALL_H
    5.36 +#define FLAC__ALL_H
    5.37 +
    5.38 +#include "export.h"
    5.39 +
    5.40 +#include "assert.h"
    5.41 +#include "callback.h"
    5.42 +#include "format.h"
    5.43 +#include "metadata.h"
    5.44 +#include "ordinals.h"
    5.45 +#include "stream_decoder.h"
    5.46 +#include "stream_encoder.h"
    5.47 +
    5.48 +/** \mainpage
    5.49 + *
    5.50 + * \section intro Introduction
    5.51 + *
    5.52 + * This is the documentation for the FLAC C and C++ APIs.  It is
    5.53 + * highly interconnected; this introduction should give you a top
    5.54 + * level idea of the structure and how to find the information you
    5.55 + * need.  As a prerequisite you should have at least a basic
    5.56 + * knowledge of the FLAC format, documented
    5.57 + * <A HREF="../format.html">here</A>.
    5.58 + *
    5.59 + * \section c_api FLAC C API
    5.60 + *
    5.61 + * The FLAC C API is the interface to libFLAC, a set of structures
    5.62 + * describing the components of FLAC streams, and functions for
    5.63 + * encoding and decoding streams, as well as manipulating FLAC
    5.64 + * metadata in files.  The public include files will be installed
    5.65 + * in your include area (for example /usr/include/FLAC/...).
    5.66 + *
    5.67 + * By writing a little code and linking against libFLAC, it is
    5.68 + * relatively easy to add FLAC support to another program.  The
    5.69 + * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
    5.70 + * Complete source code of libFLAC as well as the command-line
    5.71 + * encoder and plugins is available and is a useful source of
    5.72 + * examples.
    5.73 + *
    5.74 + * Aside from encoders and decoders, libFLAC provides a powerful
    5.75 + * metadata interface for manipulating metadata in FLAC files.  It
    5.76 + * allows the user to add, delete, and modify FLAC metadata blocks
    5.77 + * and it can automatically take advantage of PADDING blocks to avoid
    5.78 + * rewriting the entire FLAC file when changing the size of the
    5.79 + * metadata.
    5.80 + *
    5.81 + * libFLAC usually only requires the standard C library and C math
    5.82 + * library. In particular, threading is not used so there is no
    5.83 + * dependency on a thread library. However, libFLAC does not use
    5.84 + * global variables and should be thread-safe.
    5.85 + *
    5.86 + * libFLAC also supports encoding to and decoding from Ogg FLAC.
    5.87 + * However the metadata editing interfaces currently have limited
    5.88 + * read-only support for Ogg FLAC files.
    5.89 + *
    5.90 + * \section cpp_api FLAC C++ API
    5.91 + *
    5.92 + * The FLAC C++ API is a set of classes that encapsulate the
    5.93 + * structures and functions in libFLAC.  They provide slightly more
    5.94 + * functionality with respect to metadata but are otherwise
    5.95 + * equivalent.  For the most part, they share the same usage as
    5.96 + * their counterparts in libFLAC, and the FLAC C API documentation
    5.97 + * can be used as a supplement.  The public include files
    5.98 + * for the C++ API will be installed in your include area (for
    5.99 + * example /usr/include/FLAC++/...).
   5.100 + *
   5.101 + * libFLAC++ is also licensed under
   5.102 + * <A HREF="../license.html">Xiph's BSD license</A>.
   5.103 + *
   5.104 + * \section getting_started Getting Started
   5.105 + *
   5.106 + * A good starting point for learning the API is to browse through
   5.107 + * the <A HREF="modules.html">modules</A>.  Modules are logical
   5.108 + * groupings of related functions or classes, which correspond roughly
   5.109 + * to header files or sections of header files.  Each module includes a
   5.110 + * detailed description of the general usage of its functions or
   5.111 + * classes.
   5.112 + *
   5.113 + * From there you can go on to look at the documentation of
   5.114 + * individual functions.  You can see different views of the individual
   5.115 + * functions through the links in top bar across this page.
   5.116 + *
   5.117 + * If you prefer a more hands-on approach, you can jump right to some
   5.118 + * <A HREF="../documentation_example_code.html">example code</A>.
   5.119 + *
   5.120 + * \section porting_guide Porting Guide
   5.121 + *
   5.122 + * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
   5.123 + * has been introduced which gives detailed instructions on how to
   5.124 + * port your code to newer versions of FLAC.
   5.125 + *
   5.126 + * \section embedded_developers Embedded Developers
   5.127 + *
   5.128 + * libFLAC has grown larger over time as more functionality has been
   5.129 + * included, but much of it may be unnecessary for a particular embedded
   5.130 + * implementation.  Unused parts may be pruned by some simple editing of
   5.131 + * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
   5.132 + * metadata interface are all independent from each other.
   5.133 + *
   5.134 + * It is easiest to just describe the dependencies:
   5.135 + *
   5.136 + * - All modules depend on the \link flac_format Format \endlink module.
   5.137 + * - The decoders and encoders depend on the bitbuffer.
   5.138 + * - The decoder is independent of the encoder.  The encoder uses the
   5.139 + *   decoder because of the verify feature, but this can be removed if
   5.140 + *   not needed.
   5.141 + * - Parts of the metadata interface require the stream decoder (but not
   5.142 + *   the encoder).
   5.143 + * - Ogg support is selectable through the compile time macro
   5.144 + *   \c FLAC__HAS_OGG.
   5.145 + *
   5.146 + * For example, if your application only requires the stream decoder, no
   5.147 + * encoder, and no metadata interface, you can remove the stream encoder
   5.148 + * and the metadata interface, which will greatly reduce the size of the
   5.149 + * library.
   5.150 + *
   5.151 + * Also, there are several places in the libFLAC code with comments marked
   5.152 + * with "OPT:" where a #define can be changed to enable code that might be
   5.153 + * faster on a specific platform.  Experimenting with these can yield faster
   5.154 + * binaries.
   5.155 + */
   5.156 +
   5.157 +/** \defgroup porting Porting Guide for New Versions
   5.158 + *
   5.159 + * This module describes differences in the library interfaces from
   5.160 + * version to version.  It assists in the porting of code that uses
   5.161 + * the libraries to newer versions of FLAC.
   5.162 + *
   5.163 + * One simple facility for making porting easier that has been added
   5.164 + * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
   5.165 + * library's includes (e.g. \c include/FLAC/export.h).  The
   5.166 + * \c #defines mirror the libraries'
   5.167 + * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
   5.168 + * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
   5.169 + * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
   5.170 + * These can be used to support multiple versions of an API during the
   5.171 + * transition phase, e.g.
   5.172 + *
   5.173 + * \code
   5.174 + * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
   5.175 + *   legacy code
   5.176 + * #else
   5.177 + *   new code
   5.178 + * #endif
   5.179 + * \endcode
   5.180 + *
   5.181 + * The the source will work for multiple versions and the legacy code can
   5.182 + * easily be removed when the transition is complete.
   5.183 + *
   5.184 + * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
   5.185 + * include/FLAC/export.h), which can be used to determine whether or not
   5.186 + * the library has been compiled with support for Ogg FLAC.  This is
   5.187 + * simpler than trying to call an Ogg init function and catching the
   5.188 + * error.
   5.189 + */
   5.190 +
   5.191 +/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
   5.192 + *  \ingroup porting
   5.193 + *
   5.194 + *  \brief
   5.195 + *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
   5.196 + *
   5.197 + * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
   5.198 + * been simplified.  First, libOggFLAC has been merged into libFLAC and
   5.199 + * libOggFLAC++ has been merged into libFLAC++.  Second, both the three
   5.200 + * decoding layers and three encoding layers have been merged into a
   5.201 + * single stream decoder and stream encoder.  That is, the functionality
   5.202 + * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
   5.203 + * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
   5.204 + * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
   5.205 + * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  What this means
   5.206 + * is there is now a single API that can be used to encode or decode
   5.207 + * streams to/from native FLAC or Ogg FLAC and the single API can work
   5.208 + * on both seekable and non-seekable streams.
   5.209 + *
   5.210 + * Instead of creating an encoder or decoder of a certain layer, now the
   5.211 + * client will always create a FLAC__StreamEncoder or
   5.212 + * FLAC__StreamDecoder.  The old layers are now differentiated by the
   5.213 + * initialization function.  For example, for the decoder,
   5.214 + * FLAC__stream_decoder_init() has been replaced by
   5.215 + * FLAC__stream_decoder_init_stream().  This init function takes
   5.216 + * callbacks for the I/O, and the seeking callbacks are optional.  This
   5.217 + * allows the client to use the same object for seekable and
   5.218 + * non-seekable streams.  For decoding a FLAC file directly, the client
   5.219 + * can use FLAC__stream_decoder_init_file() and pass just a filename
   5.220 + * and fewer callbacks; most of the other callbacks are supplied
   5.221 + * internally.  For situations where fopen()ing by filename is not
   5.222 + * possible (e.g. Unicode filenames on Windows) the client can instead
   5.223 + * open the file itself and supply the FILE* to
   5.224 + * FLAC__stream_decoder_init_FILE().  The init functions now returns a
   5.225 + * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
   5.226 + * Since the callbacks and client data are now passed to the init
   5.227 + * function, the FLAC__stream_decoder_set_*_callback() functions and
   5.228 + * FLAC__stream_decoder_set_client_data() are no longer needed.  The
   5.229 + * rest of the calls to the decoder are the same as before.
   5.230 + *
   5.231 + * There are counterpart init functions for Ogg FLAC, e.g.
   5.232 + * FLAC__stream_decoder_init_ogg_stream().  All the rest of the calls
   5.233 + * and callbacks are the same as for native FLAC.
   5.234 + *
   5.235 + * As an example, in FLAC 1.1.2 a seekable stream decoder would have
   5.236 + * been set up like so:
   5.237 + *
   5.238 + * \code
   5.239 + * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
   5.240 + * if(decoder == NULL) do_something;
   5.241 + * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
   5.242 + * [... other settings ...]
   5.243 + * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
   5.244 + * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
   5.245 + * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
   5.246 + * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
   5.247 + * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
   5.248 + * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
   5.249 + * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
   5.250 + * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
   5.251 + * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
   5.252 + * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
   5.253 + * \endcode
   5.254 + *
   5.255 + * In FLAC 1.1.3 it is like this:
   5.256 + *
   5.257 + * \code
   5.258 + * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
   5.259 + * if(decoder == NULL) do_something;
   5.260 + * FLAC__stream_decoder_set_md5_checking(decoder, true);
   5.261 + * [... other settings ...]
   5.262 + * if(FLAC__stream_decoder_init_stream(
   5.263 + *   decoder,
   5.264 + *   my_read_callback,
   5.265 + *   my_seek_callback,      // or NULL
   5.266 + *   my_tell_callback,      // or NULL
   5.267 + *   my_length_callback,    // or NULL
   5.268 + *   my_eof_callback,       // or NULL
   5.269 + *   my_write_callback,
   5.270 + *   my_metadata_callback,  // or NULL
   5.271 + *   my_error_callback,
   5.272 + *   my_client_data
   5.273 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   5.274 + * \endcode
   5.275 + *
   5.276 + * or you could do;
   5.277 + *
   5.278 + * \code
   5.279 + * [...]
   5.280 + * FILE *file = fopen("somefile.flac","rb");
   5.281 + * if(file == NULL) do_somthing;
   5.282 + * if(FLAC__stream_decoder_init_FILE(
   5.283 + *   decoder,
   5.284 + *   file,
   5.285 + *   my_write_callback,
   5.286 + *   my_metadata_callback,  // or NULL
   5.287 + *   my_error_callback,
   5.288 + *   my_client_data
   5.289 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   5.290 + * \endcode
   5.291 + *
   5.292 + * or just:
   5.293 + *
   5.294 + * \code
   5.295 + * [...]
   5.296 + * if(FLAC__stream_decoder_init_file(
   5.297 + *   decoder,
   5.298 + *   "somefile.flac",
   5.299 + *   my_write_callback,
   5.300 + *   my_metadata_callback,  // or NULL
   5.301 + *   my_error_callback,
   5.302 + *   my_client_data
   5.303 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   5.304 + * \endcode
   5.305 + *
   5.306 + * Another small change to the decoder is in how it handles unparseable
   5.307 + * streams.  Before, when the decoder found an unparseable stream
   5.308 + * (reserved for when the decoder encounters a stream from a future
   5.309 + * encoder that it can't parse), it changed the state to
   5.310 + * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
   5.311 + * drops sync and calls the error callback with a new error code
   5.312 + * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
   5.313 + * more robust.  If your error callback does not discriminate on the the
   5.314 + * error state, your code does not need to be changed.
   5.315 + *
   5.316 + * The encoder now has a new setting:
   5.317 + * FLAC__stream_encoder_set_apodization().  This is for setting the
   5.318 + * method used to window the data before LPC analysis.  You only need to
   5.319 + * add a call to this function if the default is not suitable.   There
   5.320 + * are also two new convenience functions that may be useful:
   5.321 + * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
   5.322 + * FLAC__metadata_get_cuesheet().
   5.323 + *
   5.324 + * The \a bytes parameter to FLAC__StreamDecoderReadCallback,
   5.325 + * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
   5.326 + * is now \c size_t instead of \c unsigned.
   5.327 + */
   5.328 +
   5.329 +/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
   5.330 + *  \ingroup porting
   5.331 + *
   5.332 + *  \brief
   5.333 + *  This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
   5.334 + *
   5.335 + * There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
   5.336 + * There was a slight change in the implementation of
   5.337 + * FLAC__stream_encoder_set_metadata(); the function now makes a copy
   5.338 + * of the \a metadata array of pointers so the client no longer needs
   5.339 + * to maintain it after the call.  The objects themselves that are
   5.340 + * pointed to by the array are still not copied though and must be
   5.341 + * maintained until the call to FLAC__stream_encoder_finish().
   5.342 + */
   5.343 +
   5.344 +/** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0
   5.345 + *  \ingroup porting
   5.346 + *
   5.347 + *  \brief
   5.348 + *  This module describes porting from FLAC 1.1.4 to FLAC 1.2.0.
   5.349 + *
   5.350 + * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0.
   5.351 + * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added.
   5.352 + * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added.
   5.353 + *
   5.354 + * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN
   5.355 + * has changed to reflect the conversion of one of the reserved bits
   5.356 + * into active use.  It used to be \c 2 and now is \c 1.  However the
   5.357 + * FLAC frame header length has not changed, so to skip the proper
   5.358 + * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN +
   5.359 + * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN
   5.360 + */
   5.361 +
   5.362 +/** \defgroup flac FLAC C API
   5.363 + *
   5.364 + * The FLAC C API is the interface to libFLAC, a set of structures
   5.365 + * describing the components of FLAC streams, and functions for
   5.366 + * encoding and decoding streams, as well as manipulating FLAC
   5.367 + * metadata in files.
   5.368 + *
   5.369 + * You should start with the format components as all other modules
   5.370 + * are dependent on it.
   5.371 + */
   5.372 +
   5.373 +#endif
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/VisualC/flac/include/FLAC/assert.h	Sun Jan 01 14:40:22 2012 -0500
     6.3 @@ -0,0 +1,45 @@
     6.4 +/* libFLAC - Free Lossless Audio Codec library
     6.5 + * Copyright (C) 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__ASSERT_H
    6.36 +#define FLAC__ASSERT_H
    6.37 +
    6.38 +/* we need this since some compilers (like MSVC) leave assert()s on release code (and we don't want to use their ASSERT) */
    6.39 +#ifdef DEBUG
    6.40 +#include <assert.h>
    6.41 +#define FLAC__ASSERT(x) assert(x)
    6.42 +#define FLAC__ASSERT_DECLARATION(x) x
    6.43 +#else
    6.44 +#define FLAC__ASSERT(x)
    6.45 +#define FLAC__ASSERT_DECLARATION(x)
    6.46 +#endif
    6.47 +
    6.48 +#endif
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/VisualC/flac/include/FLAC/callback.h	Sun Jan 01 14:40:22 2012 -0500
     7.3 @@ -0,0 +1,184 @@
     7.4 +/* libFLAC - Free Lossless Audio Codec library
     7.5 + * Copyright (C) 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__CALLBACK_H
    7.36 +#define FLAC__CALLBACK_H
    7.37 +
    7.38 +#include "ordinals.h"
    7.39 +#include <stdlib.h> /* for size_t */
    7.40 +
    7.41 +/** \file include/FLAC/callback.h
    7.42 + *
    7.43 + *  \brief
    7.44 + *  This module defines the structures for describing I/O callbacks
    7.45 + *  to the other FLAC interfaces.
    7.46 + *
    7.47 + *  See the detailed documentation for callbacks in the
    7.48 + *  \link flac_callbacks callbacks \endlink module.
    7.49 + */
    7.50 +
    7.51 +/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures
    7.52 + *  \ingroup flac
    7.53 + *
    7.54 + *  \brief
    7.55 + *  This module defines the structures for describing I/O callbacks
    7.56 + *  to the other FLAC interfaces.
    7.57 + *
    7.58 + *  The purpose of the I/O callback functions is to create a common way
    7.59 + *  for the metadata interfaces to handle I/O.
    7.60 + *
    7.61 + *  Originally the metadata interfaces required filenames as the way of
    7.62 + *  specifying FLAC files to operate on.  This is problematic in some
    7.63 + *  environments so there is an additional option to specify a set of
    7.64 + *  callbacks for doing I/O on the FLAC file, instead of the filename.
    7.65 + *
    7.66 + *  In addition to the callbacks, a FLAC__IOHandle type is defined as an
    7.67 + *  opaque structure for a data source.
    7.68 + *
    7.69 + *  The callback function prototypes are similar (but not identical) to the
    7.70 + *  stdio functions fread, fwrite, fseek, ftell, feof, and fclose.  If you use
    7.71 + *  stdio streams to implement the callbacks, you can pass fread, fwrite, and
    7.72 + *  fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or
    7.73 + *  FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle
    7.74 + *  is required.  \warning You generally CANNOT directly use fseek or ftell
    7.75 + *  for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems
    7.76 + *  these use 32-bit offsets and FLAC requires 64-bit offsets to deal with
    7.77 + *  large files.  You will have to find an equivalent function (e.g. ftello),
    7.78 + *  or write a wrapper.  The same is true for feof() since this is usually
    7.79 + *  implemented as a macro, not as a function whose address can be taken.
    7.80 + *
    7.81 + * \{
    7.82 + */
    7.83 +
    7.84 +#ifdef __cplusplus
    7.85 +extern "C" {
    7.86 +#endif
    7.87 +
    7.88 +/** This is the opaque handle type used by the callbacks.  Typically
    7.89 + *  this is a \c FILE* or address of a file descriptor.
    7.90 + */
    7.91 +typedef void* FLAC__IOHandle;
    7.92 +
    7.93 +/** Signature for the read callback.
    7.94 + *  The signature and semantics match POSIX fread() implementations
    7.95 + *  and can generally be used interchangeably.
    7.96 + *
    7.97 + * \param  ptr      The address of the read buffer.
    7.98 + * \param  size     The size of the records to be read.
    7.99 + * \param  nmemb    The number of records to be read.
   7.100 + * \param  handle   The handle to the data source.
   7.101 + * \retval size_t
   7.102 + *    The number of records read.
   7.103 + */
   7.104 +typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   7.105 +
   7.106 +/** Signature for the write callback.
   7.107 + *  The signature and semantics match POSIX fwrite() implementations
   7.108 + *  and can generally be used interchangeably.
   7.109 + *
   7.110 + * \param  ptr      The address of the write buffer.
   7.111 + * \param  size     The size of the records to be written.
   7.112 + * \param  nmemb    The number of records to be written.
   7.113 + * \param  handle   The handle to the data source.
   7.114 + * \retval size_t
   7.115 + *    The number of records written.
   7.116 + */
   7.117 +typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle);
   7.118 +
   7.119 +/** Signature for the seek callback.
   7.120 + *  The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
   7.121 + *  EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long'
   7.122 + *  and 32-bits wide.
   7.123 + *
   7.124 + * \param  handle   The handle to the data source.
   7.125 + * \param  offset   The new position, relative to \a whence
   7.126 + * \param  whence   \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END
   7.127 + * \retval int
   7.128 + *    \c 0 on success, \c -1 on error.
   7.129 + */
   7.130 +typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence);
   7.131 +
   7.132 +/** Signature for the tell callback.
   7.133 + *  The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
   7.134 + *  EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long'
   7.135 + *  and 32-bits wide.
   7.136 + *
   7.137 + * \param  handle   The handle to the data source.
   7.138 + * \retval FLAC__int64
   7.139 + *    The current position on success, \c -1 on error.
   7.140 + */
   7.141 +typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle);
   7.142 +
   7.143 +/** Signature for the EOF callback.
   7.144 + *  The signature and semantics mostly match POSIX feof() but WATCHOUT:
   7.145 + *  on many systems, feof() is a macro, so in this case a wrapper function
   7.146 + *  must be provided instead.
   7.147 + *
   7.148 + * \param  handle   The handle to the data source.
   7.149 + * \retval int
   7.150 + *    \c 0 if not at end of file, nonzero if at end of file.
   7.151 + */
   7.152 +typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle);
   7.153 +
   7.154 +/** Signature for the close callback.
   7.155 + *  The signature and semantics match POSIX fclose() implementations
   7.156 + *  and can generally be used interchangeably.
   7.157 + *
   7.158 + * \param  handle   The handle to the data source.
   7.159 + * \retval int
   7.160 + *    \c 0 on success, \c EOF on error.
   7.161 + */
   7.162 +typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle);
   7.163 +
   7.164 +/** A structure for holding a set of callbacks.
   7.165 + *  Each FLAC interface that requires a FLAC__IOCallbacks structure will
   7.166 + *  describe which of the callbacks are required.  The ones that are not
   7.167 + *  required may be set to NULL.
   7.168 + *
   7.169 + *  If the seek requirement for an interface is optional, you can signify that
   7.170 + *  a data sorce is not seekable by setting the \a seek field to \c NULL.
   7.171 + */
   7.172 +typedef struct {
   7.173 +	FLAC__IOCallback_Read read;
   7.174 +	FLAC__IOCallback_Write write;
   7.175 +	FLAC__IOCallback_Seek seek;
   7.176 +	FLAC__IOCallback_Tell tell;
   7.177 +	FLAC__IOCallback_Eof eof;
   7.178 +	FLAC__IOCallback_Close close;
   7.179 +} FLAC__IOCallbacks;
   7.180 +
   7.181 +/* \} */
   7.182 +
   7.183 +#ifdef __cplusplus
   7.184 +}
   7.185 +#endif
   7.186 +
   7.187 +#endif
     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/VisualC/flac/include/FLAC/export.h	Sun Jan 01 14:40:22 2012 -0500
     8.3 @@ -0,0 +1,91 @@
     8.4 +/* libFLAC - Free Lossless Audio Codec library
     8.5 + * Copyright (C) 2000,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__EXPORT_H
    8.36 +#define FLAC__EXPORT_H
    8.37 +
    8.38 +/** \file include/FLAC/export.h
    8.39 + *
    8.40 + *  \brief
    8.41 + *  This module contains #defines and symbols for exporting function
    8.42 + *  calls, and providing version information and compiled-in features.
    8.43 + *
    8.44 + *  See the \link flac_export export \endlink module.
    8.45 + */
    8.46 +
    8.47 +/** \defgroup flac_export FLAC/export.h: export symbols
    8.48 + *  \ingroup flac
    8.49 + *
    8.50 + *  \brief
    8.51 + *  This module contains #defines and symbols for exporting function
    8.52 + *  calls, and providing version information and compiled-in features.
    8.53 + *
    8.54 + *  If you are compiling with MSVC and will link to the static library
    8.55 + *  (libFLAC.lib) you should define FLAC__NO_DLL in your project to
    8.56 + *  make sure the symbols are exported properly.
    8.57 + *
    8.58 + * \{
    8.59 + */
    8.60 +
    8.61 +#if defined(FLAC__NO_DLL) || !defined(_MSC_VER)
    8.62 +#define FLAC_API
    8.63 +
    8.64 +#else
    8.65 +
    8.66 +#ifdef FLAC_API_EXPORTS
    8.67 +#define	FLAC_API	_declspec(dllexport)
    8.68 +#else
    8.69 +#define FLAC_API	_declspec(dllimport)
    8.70 +
    8.71 +#endif
    8.72 +#endif
    8.73 +
    8.74 +/** These #defines will mirror the libtool-based library version number, see
    8.75 + * http://www.gnu.org/software/libtool/manual.html#Libtool-versioning
    8.76 + */
    8.77 +#define FLAC_API_VERSION_CURRENT 10
    8.78 +#define FLAC_API_VERSION_REVISION 0 /**< see above */
    8.79 +#define FLAC_API_VERSION_AGE 2 /**< see above */
    8.80 +
    8.81 +#ifdef __cplusplus
    8.82 +extern "C" {
    8.83 +#endif
    8.84 +
    8.85 +/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */
    8.86 +extern FLAC_API int FLAC_API_SUPPORTS_OGG_FLAC;
    8.87 +
    8.88 +#ifdef __cplusplus
    8.89 +}
    8.90 +#endif
    8.91 +
    8.92 +/* \} */
    8.93 +
    8.94 +#endif
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/VisualC/flac/include/FLAC/format.h	Sun Jan 01 14:40:22 2012 -0500
     9.3 @@ -0,0 +1,1010 @@
     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__FORMAT_H
    9.36 +#define FLAC__FORMAT_H
    9.37 +
    9.38 +#include "export.h"
    9.39 +#include "ordinals.h"
    9.40 +
    9.41 +#ifdef __cplusplus
    9.42 +extern "C" {
    9.43 +#endif
    9.44 +
    9.45 +/** \file include/FLAC/format.h
    9.46 + *
    9.47 + *  \brief
    9.48 + *  This module contains structure definitions for the representation
    9.49 + *  of FLAC format components in memory.  These are the basic
    9.50 + *  structures used by the rest of the interfaces.
    9.51 + *
    9.52 + *  See the detailed documentation in the
    9.53 + *  \link flac_format format \endlink module.
    9.54 + */
    9.55 +
    9.56 +/** \defgroup flac_format FLAC/format.h: format components
    9.57 + *  \ingroup flac
    9.58 + *
    9.59 + *  \brief
    9.60 + *  This module contains structure definitions for the representation
    9.61 + *  of FLAC format components in memory.  These are the basic
    9.62 + *  structures used by the rest of the interfaces.
    9.63 + *
    9.64 + *  First, you should be familiar with the
    9.65 + *  <A HREF="../format.html">FLAC format</A>.  Many of the values here
    9.66 + *  follow directly from the specification.  As a user of libFLAC, the
    9.67 + *  interesting parts really are the structures that describe the frame
    9.68 + *  header and metadata blocks.
    9.69 + *
    9.70 + *  The format structures here are very primitive, designed to store
    9.71 + *  information in an efficient way.  Reading information from the
    9.72 + *  structures is easy but creating or modifying them directly is
    9.73 + *  more complex.  For the most part, as a user of a library, editing
    9.74 + *  is not necessary; however, for metadata blocks it is, so there are
    9.75 + *  convenience functions provided in the \link flac_metadata metadata
    9.76 + *  module \endlink to simplify the manipulation of metadata blocks.
    9.77 + *
    9.78 + * \note
    9.79 + * It's not the best convention, but symbols ending in _LEN are in bits
    9.80 + * and _LENGTH are in bytes.  _LENGTH symbols are \#defines instead of
    9.81 + * global variables because they are usually used when declaring byte
    9.82 + * arrays and some compilers require compile-time knowledge of array
    9.83 + * sizes when declared on the stack.
    9.84 + *
    9.85 + * \{
    9.86 + */
    9.87 +
    9.88 +
    9.89 +/*
    9.90 +	Most of the values described in this file are defined by the FLAC
    9.91 +	format specification.  There is nothing to tune here.
    9.92 +*/
    9.93 +
    9.94 +/** The largest legal metadata type code. */
    9.95 +#define FLAC__MAX_METADATA_TYPE_CODE (126u)
    9.96 +
    9.97 +/** The minimum block size, in samples, permitted by the format. */
    9.98 +#define FLAC__MIN_BLOCK_SIZE (16u)
    9.99 +
   9.100 +/** The maximum block size, in samples, permitted by the format. */
   9.101 +#define FLAC__MAX_BLOCK_SIZE (65535u)
   9.102 +
   9.103 +/** The maximum block size, in samples, permitted by the FLAC subset for
   9.104 + *  sample rates up to 48kHz. */
   9.105 +#define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u)
   9.106 +
   9.107 +/** The maximum number of channels permitted by the format. */
   9.108 +#define FLAC__MAX_CHANNELS (8u)
   9.109 +
   9.110 +/** The minimum sample resolution permitted by the format. */
   9.111 +#define FLAC__MIN_BITS_PER_SAMPLE (4u)
   9.112 +
   9.113 +/** The maximum sample resolution permitted by the format. */
   9.114 +#define FLAC__MAX_BITS_PER_SAMPLE (32u)
   9.115 +
   9.116 +/** The maximum sample resolution permitted by libFLAC.
   9.117 + *
   9.118 + * \warning
   9.119 + * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format.  However,
   9.120 + * the reference encoder/decoder is currently limited to 24 bits because
   9.121 + * of prevalent 32-bit math, so make sure and use this value when
   9.122 + * appropriate.
   9.123 + */
   9.124 +#define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
   9.125 +
   9.126 +/** The maximum sample rate permitted by the format.  The value is
   9.127 + *  ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A>
   9.128 + *  as to why.
   9.129 + */
   9.130 +#define FLAC__MAX_SAMPLE_RATE (655350u)
   9.131 +
   9.132 +/** The maximum LPC order permitted by the format. */
   9.133 +#define FLAC__MAX_LPC_ORDER (32u)
   9.134 +
   9.135 +/** The maximum LPC order permitted by the FLAC subset for sample rates
   9.136 + *  up to 48kHz. */
   9.137 +#define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u)
   9.138 +
   9.139 +/** The minimum quantized linear predictor coefficient precision
   9.140 + *  permitted by the format.
   9.141 + */
   9.142 +#define FLAC__MIN_QLP_COEFF_PRECISION (5u)
   9.143 +
   9.144 +/** The maximum quantized linear predictor coefficient precision
   9.145 + *  permitted by the format.
   9.146 + */
   9.147 +#define FLAC__MAX_QLP_COEFF_PRECISION (15u)
   9.148 +
   9.149 +/** The maximum order of the fixed predictors permitted by the format. */
   9.150 +#define FLAC__MAX_FIXED_ORDER (4u)
   9.151 +
   9.152 +/** The maximum Rice partition order permitted by the format. */
   9.153 +#define FLAC__MAX_RICE_PARTITION_ORDER (15u)
   9.154 +
   9.155 +/** The maximum Rice partition order permitted by the FLAC Subset. */
   9.156 +#define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
   9.157 +
   9.158 +/** The version string of the release, stamped onto the libraries and binaries.
   9.159 + *
   9.160 + * \note
   9.161 + * This does not correspond to the shared library version number, which
   9.162 + * is used to determine binary compatibility.
   9.163 + */
   9.164 +extern FLAC_API const char *FLAC__VERSION_STRING;
   9.165 +
   9.166 +/** The vendor string inserted by the encoder into the VORBIS_COMMENT block.
   9.167 + *  This is a NUL-terminated ASCII string; when inserted into the
   9.168 + *  VORBIS_COMMENT the trailing null is stripped.
   9.169 + */
   9.170 +extern FLAC_API const char *FLAC__VENDOR_STRING;
   9.171 +
   9.172 +/** The byte string representation of the beginning of a FLAC stream. */
   9.173 +extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
   9.174 +
   9.175 +/** The 32-bit integer big-endian representation of the beginning of
   9.176 + *  a FLAC stream.
   9.177 + */
   9.178 +extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
   9.179 +
   9.180 +/** The length of the FLAC signature in bits. */
   9.181 +extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
   9.182 +
   9.183 +/** The length of the FLAC signature in bytes. */
   9.184 +#define FLAC__STREAM_SYNC_LENGTH (4u)
   9.185 +
   9.186 +
   9.187 +/*****************************************************************************
   9.188 + *
   9.189 + * Subframe structures
   9.190 + *
   9.191 + *****************************************************************************/
   9.192 +
   9.193 +/*****************************************************************************/
   9.194 +
   9.195 +/** An enumeration of the available entropy coding methods. */
   9.196 +typedef enum {
   9.197 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0,
   9.198 +	/**< Residual is coded by partitioning into contexts, each with it's own
   9.199 +	 * 4-bit Rice parameter. */
   9.200 +
   9.201 +	FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2 = 1
   9.202 +	/**< Residual is coded by partitioning into contexts, each with it's own
   9.203 +	 * 5-bit Rice parameter. */
   9.204 +} FLAC__EntropyCodingMethodType;
   9.205 +
   9.206 +/** Maps a FLAC__EntropyCodingMethodType to a C string.
   9.207 + *
   9.208 + *  Using a FLAC__EntropyCodingMethodType as the index to this array will
   9.209 + *  give the string equivalent.  The contents should not be modified.
   9.210 + */
   9.211 +extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
   9.212 +
   9.213 +
   9.214 +/** Contents of a Rice partitioned residual
   9.215 + */
   9.216 +typedef struct {
   9.217 +
   9.218 +	unsigned *parameters;
   9.219 +	/**< The Rice parameters for each context. */
   9.220 +
   9.221 +	unsigned *raw_bits;
   9.222 +	/**< Widths for escape-coded partitions.  Will be non-zero for escaped
   9.223 +	 * partitions and zero for unescaped partitions.
   9.224 +	 */
   9.225 +
   9.226 +	unsigned capacity_by_order;
   9.227 +	/**< The capacity of the \a parameters and \a raw_bits arrays
   9.228 +	 * specified as an order, i.e. the number of array elements
   9.229 +	 * allocated is 2 ^ \a capacity_by_order.
   9.230 +	 */
   9.231 +} FLAC__EntropyCodingMethod_PartitionedRiceContents;
   9.232 +
   9.233 +/** Header for a Rice partitioned residual.  (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>)
   9.234 + */
   9.235 +typedef struct {
   9.236 +
   9.237 +	unsigned order;
   9.238 +	/**< The partition order, i.e. # of contexts = 2 ^ \a order. */
   9.239 +
   9.240 +	const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
   9.241 +	/**< The context's Rice parameters and/or raw bits. */
   9.242 +
   9.243 +} FLAC__EntropyCodingMethod_PartitionedRice;
   9.244 +
   9.245 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */
   9.246 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */
   9.247 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN; /**< == 5 (bits) */
   9.248 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */
   9.249 +
   9.250 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
   9.251 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
   9.252 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_ESCAPE_PARAMETER;
   9.253 +/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN)-1 */
   9.254 +
   9.255 +/** Header for the entropy coding method.  (c.f. <A HREF="../format.html#residual">format specification</A>)
   9.256 + */
   9.257 +typedef struct {
   9.258 +	FLAC__EntropyCodingMethodType type;
   9.259 +	union {
   9.260 +		FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
   9.261 +	} data;
   9.262 +} FLAC__EntropyCodingMethod;
   9.263 +
   9.264 +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */
   9.265 +
   9.266 +/*****************************************************************************/
   9.267 +
   9.268 +/** An enumeration of the available subframe types. */
   9.269 +typedef enum {
   9.270 +	FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */
   9.271 +	FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */
   9.272 +	FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */
   9.273 +	FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */
   9.274 +} FLAC__SubframeType;
   9.275 +
   9.276 +/** Maps a FLAC__SubframeType to a C string.
   9.277 + *
   9.278 + *  Using a FLAC__SubframeType as the index to this array will
   9.279 + *  give the string equivalent.  The contents should not be modified.
   9.280 + */
   9.281 +extern FLAC_API const char * const FLAC__SubframeTypeString[];
   9.282 +
   9.283 +
   9.284 +/** CONSTANT subframe.  (c.f. <A HREF="../format.html#subframe_constant">format specification</A>)
   9.285 + */
   9.286 +typedef struct {
   9.287 +	FLAC__int32 value; /**< The constant signal value. */
   9.288 +} FLAC__Subframe_Constant;
   9.289 +
   9.290 +
   9.291 +/** VERBATIM subframe.  (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>)
   9.292 + */
   9.293 +typedef struct {
   9.294 +	const FLAC__int32 *data; /**< A pointer to verbatim signal. */
   9.295 +} FLAC__Subframe_Verbatim;
   9.296 +
   9.297 +
   9.298 +/** FIXED subframe.  (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>)
   9.299 + */
   9.300 +typedef struct {
   9.301 +	FLAC__EntropyCodingMethod entropy_coding_method;
   9.302 +	/**< The residual coding method. */
   9.303 +
   9.304 +	unsigned order;
   9.305 +	/**< The polynomial order. */
   9.306 +
   9.307 +	FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
   9.308 +	/**< Warmup samples to prime the predictor, length == order. */
   9.309 +
   9.310 +	const FLAC__int32 *residual;
   9.311 +	/**< The residual signal, length == (blocksize minus order) samples. */
   9.312 +} FLAC__Subframe_Fixed;
   9.313 +
   9.314 +
   9.315 +/** LPC subframe.  (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>)
   9.316 + */
   9.317 +typedef struct {
   9.318 +	FLAC__EntropyCodingMethod entropy_coding_method;
   9.319 +	/**< The residual coding method. */
   9.320 +
   9.321 +	unsigned order;
   9.322 +	/**< The FIR order. */
   9.323 +
   9.324 +	unsigned qlp_coeff_precision;
   9.325 +	/**< Quantized FIR filter coefficient precision in bits. */
   9.326 +
   9.327 +	int quantization_level;
   9.328 +	/**< The qlp coeff shift needed. */
   9.329 +
   9.330 +	FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
   9.331 +	/**< FIR filter coefficients. */
   9.332 +
   9.333 +	FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
   9.334 +	/**< Warmup samples to prime the predictor, length == order. */
   9.335 +
   9.336 +	const FLAC__int32 *residual;
   9.337 +	/**< The residual signal, length == (blocksize minus order) samples. */
   9.338 +} FLAC__Subframe_LPC;
   9.339 +
   9.340 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */
   9.341 +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */
   9.342 +
   9.343 +
   9.344 +/** FLAC subframe structure.  (c.f. <A HREF="../format.html#subframe">format specification</A>)
   9.345 + */
   9.346 +typedef struct {
   9.347 +	FLAC__SubframeType type;
   9.348 +	union {
   9.349 +		FLAC__Subframe_Constant constant;
   9.350 +		FLAC__Subframe_Fixed fixed;
   9.351 +		FLAC__Subframe_LPC lpc;
   9.352 +		FLAC__Subframe_Verbatim verbatim;
   9.353 +	} data;
   9.354 +	unsigned wasted_bits;
   9.355 +} FLAC__Subframe;
   9.356 +
   9.357 +/** == 1 (bit)
   9.358 + *
   9.359 + * This used to be a zero-padding bit (hence the name
   9.360 + * FLAC__SUBFRAME_ZERO_PAD_LEN) but is now a reserved bit.  It still has a
   9.361 + * mandatory value of \c 0 but in the future may take on the value \c 0 or \c 1
   9.362 + * to mean something else.
   9.363 + */
   9.364 +extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN;
   9.365 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */
   9.366 +extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */
   9.367 +
   9.368 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */
   9.369 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */
   9.370 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */
   9.371 +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */
   9.372 +
   9.373 +/*****************************************************************************/
   9.374 +
   9.375 +
   9.376 +/*****************************************************************************
   9.377 + *
   9.378 + * Frame structures
   9.379 + *
   9.380 + *****************************************************************************/
   9.381 +
   9.382 +/** An enumeration of the available channel assignments. */
   9.383 +typedef enum {
   9.384 +	FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */
   9.385 +	FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */
   9.386 +	FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */
   9.387 +	FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */
   9.388 +} FLAC__ChannelAssignment;
   9.389 +
   9.390 +/** Maps a FLAC__ChannelAssignment to a C string.
   9.391 + *
   9.392 + *  Using a FLAC__ChannelAssignment as the index to this array will
   9.393 + *  give the string equivalent.  The contents should not be modified.
   9.394 + */
   9.395 +extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
   9.396 +
   9.397 +/** An enumeration of the possible frame numbering methods. */
   9.398 +typedef enum {
   9.399 +	FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */
   9.400 +	FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */
   9.401 +} FLAC__FrameNumberType;
   9.402 +
   9.403 +/** Maps a FLAC__FrameNumberType to a C string.
   9.404 + *
   9.405 + *  Using a FLAC__FrameNumberType as the index to this array will
   9.406 + *  give the string equivalent.  The contents should not be modified.
   9.407 + */
   9.408 +extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
   9.409 +
   9.410 +
   9.411 +/** FLAC frame header structure.  (c.f. <A HREF="../format.html#frame_header">format specification</A>)
   9.412 + */
   9.413 +typedef struct {
   9.414 +	unsigned blocksize;
   9.415 +	/**< The number of samples per subframe. */
   9.416 +
   9.417 +	unsigned sample_rate;
   9.418 +	/**< The sample rate in Hz. */
   9.419 +
   9.420 +	unsigned channels;
   9.421 +	/**< The number of channels (== number of subframes). */
   9.422 +
   9.423 +	FLAC__ChannelAssignment channel_assignment;
   9.424 +	/**< The channel assignment for the frame. */
   9.425 +
   9.426 +	unsigned bits_per_sample;
   9.427 +	/**< The sample resolution. */
   9.428 +
   9.429 +	FLAC__FrameNumberType number_type;
   9.430 +	/**< The numbering scheme used for the frame.  As a convenience, the
   9.431 +	 * decoder will always convert a frame number to a sample number because
   9.432 +	 * the rules are complex. */
   9.433 +
   9.434 +	union {
   9.435 +		FLAC__uint32 frame_number;
   9.436 +		FLAC__uint64 sample_number;
   9.437 +	} number;
   9.438 +	/**< The frame number or sample number of first sample in frame;
   9.439 +	 * use the \a number_type value to determine which to use. */
   9.440 +
   9.441 +	FLAC__uint8 crc;
   9.442 +	/**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0)
   9.443 +	 * of the raw frame header bytes, meaning everything before the CRC byte
   9.444 +	 * including the sync code.
   9.445 +	 */
   9.446 +} FLAC__FrameHeader;
   9.447 +
   9.448 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */
   9.449 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */
   9.450 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 1 (bits) */
   9.451 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN; /**< == 1 (bits) */
   9.452 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */
   9.453 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */
   9.454 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */
   9.455 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */
   9.456 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */
   9.457 +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */
   9.458 +
   9.459 +
   9.460 +/** FLAC frame footer structure.  (c.f. <A HREF="../format.html#frame_footer">format specification</A>)
   9.461 + */
   9.462 +typedef struct {
   9.463 +	FLAC__uint16 crc;
   9.464 +	/**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with
   9.465 +	 * 0) of the bytes before the crc, back to and including the frame header
   9.466 +	 * sync code.
   9.467 +	 */
   9.468 +} FLAC__FrameFooter;
   9.469 +
   9.470 +extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */
   9.471 +
   9.472 +
   9.473 +/** FLAC frame structure.  (c.f. <A HREF="../format.html#frame">format specification</A>)
   9.474 + */
   9.475 +typedef struct {
   9.476 +	FLAC__FrameHeader header;
   9.477 +	FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
   9.478 +	FLAC__FrameFooter footer;
   9.479 +} FLAC__Frame;
   9.480 +
   9.481 +/*****************************************************************************/
   9.482 +
   9.483 +
   9.484 +/*****************************************************************************
   9.485 + *
   9.486 + * Meta-data structures
   9.487 + *
   9.488 + *****************************************************************************/
   9.489 +
   9.490 +/** An enumeration of the available metadata block types. */
   9.491 +typedef enum {
   9.492 +
   9.493 +	FLAC__METADATA_TYPE_STREAMINFO = 0,
   9.494 +	/**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */
   9.495 +
   9.496 +	FLAC__METADATA_TYPE_PADDING = 1,
   9.497 +	/**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */
   9.498 +
   9.499 +	FLAC__METADATA_TYPE_APPLICATION = 2,
   9.500 +	/**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */
   9.501 +
   9.502 +	FLAC__METADATA_TYPE_SEEKTABLE = 3,
   9.503 +	/**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
   9.504 +
   9.505 +	FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
   9.506 +	/**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */
   9.507 +
   9.508 +	FLAC__METADATA_TYPE_CUESHEET = 5,
   9.509 +	/**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
   9.510 +
   9.511 +	FLAC__METADATA_TYPE_PICTURE = 6,
   9.512 +	/**< <A HREF="../format.html#metadata_block_picture">PICTURE</A> block */
   9.513 +
   9.514 +	FLAC__METADATA_TYPE_UNDEFINED = 7
   9.515 +	/**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
   9.516 +
   9.517 +} FLAC__MetadataType;
   9.518 +
   9.519 +/** Maps a FLAC__MetadataType to a C string.
   9.520 + *
   9.521 + *  Using a FLAC__MetadataType as the index to this array will
   9.522 + *  give the string equivalent.  The contents should not be modified.
   9.523 + */
   9.524 +extern FLAC_API const char * const FLAC__MetadataTypeString[];
   9.525 +
   9.526 +
   9.527 +/** FLAC STREAMINFO structure.  (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>)
   9.528 + */
   9.529 +typedef struct {
   9.530 +	unsigned min_blocksize, max_blocksize;
   9.531 +	unsigned min_framesize, max_framesize;
   9.532 +	unsigned sample_rate;
   9.533 +	unsigned channels;
   9.534 +	unsigned bits_per_sample;
   9.535 +	FLAC__uint64 total_samples;
   9.536 +	FLAC__byte md5sum[16];
   9.537 +} FLAC__StreamMetadata_StreamInfo;
   9.538 +
   9.539 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */
   9.540 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */
   9.541 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */
   9.542 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */
   9.543 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */
   9.544 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */
   9.545 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */
   9.546 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */
   9.547 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */
   9.548 +
   9.549 +/** The total stream length of the STREAMINFO block in bytes. */
   9.550 +#define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
   9.551 +
   9.552 +/** FLAC PADDING structure.  (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>)
   9.553 + */
   9.554 +typedef struct {
   9.555 +	int dummy;
   9.556 +	/**< Conceptually this is an empty struct since we don't store the
   9.557 +	 * padding bytes.  Empty structs are not allowed by some C compilers,
   9.558 +	 * hence the dummy.
   9.559 +	 */
   9.560 +} FLAC__StreamMetadata_Padding;
   9.561 +
   9.562 +
   9.563 +/** FLAC APPLICATION structure.  (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>)
   9.564 + */
   9.565 +typedef struct {
   9.566 +	FLAC__byte id[4];
   9.567 +	FLAC__byte *data;
   9.568 +} FLAC__StreamMetadata_Application;
   9.569 +
   9.570 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */
   9.571 +
   9.572 +/** SeekPoint structure used in SEEKTABLE blocks.  (c.f. <A HREF="../format.html#seekpoint">format specification</A>)
   9.573 + */
   9.574 +typedef struct {
   9.575 +	FLAC__uint64 sample_number;
   9.576 +	/**<  The sample number of the target frame. */
   9.577 +
   9.578 +	FLAC__uint64 stream_offset;
   9.579 +	/**< The offset, in bytes, of the target frame with respect to
   9.580 +	 * beginning of the first frame. */
   9.581 +
   9.582 +	unsigned frame_samples;
   9.583 +	/**< The number of samples in the target frame. */
   9.584 +} FLAC__StreamMetadata_SeekPoint;
   9.585 +
   9.586 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */
   9.587 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */
   9.588 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */
   9.589 +
   9.590 +/** The total stream length of a seek point in bytes. */
   9.591 +#define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
   9.592 +
   9.593 +/** The value used in the \a sample_number field of
   9.594 + *  FLAC__StreamMetadataSeekPoint used to indicate a placeholder
   9.595 + *  point (== 0xffffffffffffffff).
   9.596 + */
   9.597 +extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
   9.598 +
   9.599 +
   9.600 +/** FLAC SEEKTABLE structure.  (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>)
   9.601 + *
   9.602 + * \note From the format specification:
   9.603 + * - The seek points must be sorted by ascending sample number.
   9.604 + * - Each seek point's sample number must be the first sample of the
   9.605 + *   target frame.
   9.606 + * - Each seek point's sample number must be unique within the table.
   9.607 + * - Existence of a SEEKTABLE block implies a correct setting of
   9.608 + *   total_samples in the stream_info block.
   9.609 + * - Behavior is undefined when more than one SEEKTABLE block is
   9.610 + *   present in a stream.
   9.611 + */
   9.612 +typedef struct {
   9.613 +	unsigned num_points;
   9.614 +	FLAC__StreamMetadata_SeekPoint *points;
   9.615 +} FLAC__StreamMetadata_SeekTable;
   9.616 +
   9.617 +
   9.618 +/** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
   9.619 + *
   9.620 + *  For convenience, the APIs maintain a trailing NUL character at the end of
   9.621 + *  \a entry which is not counted toward \a length, i.e.
   9.622 + *  \code strlen(entry) == length \endcode
   9.623 + */
   9.624 +typedef struct {
   9.625 +	FLAC__uint32 length;
   9.626 +	FLAC__byte *entry;
   9.627 +} FLAC__StreamMetadata_VorbisComment_Entry;
   9.628 +
   9.629 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */
   9.630 +
   9.631 +
   9.632 +/** FLAC VORBIS_COMMENT structure.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
   9.633 + */
   9.634 +typedef struct {
   9.635 +	FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
   9.636 +	FLAC__uint32 num_comments;
   9.637 +	FLAC__StreamMetadata_VorbisComment_Entry *comments;
   9.638 +} FLAC__StreamMetadata_VorbisComment;
   9.639 +
   9.640 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
   9.641 +
   9.642 +
   9.643 +/** FLAC CUESHEET track index structure.  (See the
   9.644 + * <A HREF="../format.html#cuesheet_track_index">format specification</A> for
   9.645 + * the full description of each field.)
   9.646 + */
   9.647 +typedef struct {
   9.648 +	FLAC__uint64 offset;
   9.649 +	/**< Offset in samples, relative to the track offset, of the index
   9.650 +	 * point.
   9.651 +	 */
   9.652 +
   9.653 +	FLAC__byte number;
   9.654 +	/**< The index point number. */
   9.655 +} FLAC__StreamMetadata_CueSheet_Index;
   9.656 +
   9.657 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
   9.658 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */
   9.659 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */
   9.660 +
   9.661 +
   9.662 +/** FLAC CUESHEET track structure.  (See the
   9.663 + * <A HREF="../format.html#cuesheet_track">format specification</A> for
   9.664 + * the full description of each field.)
   9.665 + */
   9.666 +typedef struct {
   9.667 +	FLAC__uint64 offset;
   9.668 +	/**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
   9.669 +
   9.670 +	FLAC__byte number;
   9.671 +	/**< The track number. */
   9.672 +
   9.673 +	char isrc[13];
   9.674 +	/**< Track ISRC.  This is a 12-digit alphanumeric code plus a trailing \c NUL byte */
   9.675 +
   9.676 +	unsigned type:1;
   9.677 +	/**< The track type: 0 for audio, 1 for non-audio. */
   9.678 +
   9.679 +	unsigned pre_emphasis:1;
   9.680 +	/**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
   9.681 +
   9.682 +	FLAC__byte num_indices;
   9.683 +	/**< The number of track index points. */
   9.684 +
   9.685 +	FLAC__StreamMetadata_CueSheet_Index *indices;
   9.686 +	/**< NULL if num_indices == 0, else pointer to array of index points. */
   9.687 +
   9.688 +} FLAC__StreamMetadata_CueSheet_Track;
   9.689 +
   9.690 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
   9.691 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */
   9.692 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */
   9.693 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */
   9.694 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */
   9.695 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */
   9.696 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
   9.697 +
   9.698 +
   9.699 +/** FLAC CUESHEET structure.  (See the
   9.700 + * <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
   9.701 + * for the full description of each field.)
   9.702 + */
   9.703 +typedef struct {
   9.704 +	char media_catalog_number[129];
   9.705 +	/**< Media catalog number, in ASCII printable characters 0x20-0x7e.  In
   9.706 +	 * general, the media catalog number may be 0 to 128 bytes long; any
   9.707 +	 * unused characters should be right-padded with NUL characters.
   9.708 +	 */
   9.709 +
   9.710 +	FLAC__uint64 lead_in;
   9.711 +	/**< The number of lead-in samples. */
   9.712 +
   9.713 +	FLAC__bool is_cd;
   9.714 +	/**< \c true if CUESHEET corresponds to a Compact Disc, else \c false. */
   9.715 +
   9.716 +	unsigned num_tracks;
   9.717 +	/**< The number of tracks. */
   9.718 +
   9.719 +	FLAC__StreamMetadata_CueSheet_Track *tracks;
   9.720 +	/**< NULL if num_tracks == 0, else pointer to array of tracks. */
   9.721 +
   9.722 +} FLAC__StreamMetadata_CueSheet;
   9.723 +
   9.724 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
   9.725 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */
   9.726 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */
   9.727 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */
   9.728 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
   9.729 +
   9.730 +
   9.731 +/** An enumeration of the PICTURE types (see FLAC__StreamMetadataPicture and id3 v2.4 APIC tag). */
   9.732 +typedef enum {
   9.733 +	FLAC__STREAM_METADATA_PICTURE_TYPE_OTHER = 0, /**< Other */
   9.734 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON_STANDARD = 1, /**< 32x32 pixels 'file icon' (PNG only) */
   9.735 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON = 2, /**< Other file icon */
   9.736 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FRONT_COVER = 3, /**< Cover (front) */
   9.737 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BACK_COVER = 4, /**< Cover (back) */
   9.738 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAFLET_PAGE = 5, /**< Leaflet page */
   9.739 +	FLAC__STREAM_METADATA_PICTURE_TYPE_MEDIA = 6, /**< Media (e.g. label side of CD) */
   9.740 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LEAD_ARTIST = 7, /**< Lead artist/lead performer/soloist */
   9.741 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ARTIST = 8, /**< Artist/performer */
   9.742 +	FLAC__STREAM_METADATA_PICTURE_TYPE_CONDUCTOR = 9, /**< Conductor */
   9.743 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND = 10, /**< Band/Orchestra */
   9.744 +	FLAC__STREAM_METADATA_PICTURE_TYPE_COMPOSER = 11, /**< Composer */
   9.745 +	FLAC__STREAM_METADATA_PICTURE_TYPE_LYRICIST = 12, /**< Lyricist/text writer */
   9.746 +	FLAC__STREAM_METADATA_PICTURE_TYPE_RECORDING_LOCATION = 13, /**< Recording Location */
   9.747 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_RECORDING = 14, /**< During recording */
   9.748 +	FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_PERFORMANCE = 15, /**< During performance */
   9.749 +	FLAC__STREAM_METADATA_PICTURE_TYPE_VIDEO_SCREEN_CAPTURE = 16, /**< Movie/video screen capture */
   9.750 +	FLAC__STREAM_METADATA_PICTURE_TYPE_FISH = 17, /**< A bright coloured fish */
   9.751 +	FLAC__STREAM_METADATA_PICTURE_TYPE_ILLUSTRATION = 18, /**< Illustration */
   9.752 +	FLAC__STREAM_METADATA_PICTURE_TYPE_BAND_LOGOTYPE = 19, /**< Band/artist logotype */
   9.753 +	FLAC__STREAM_METADATA_PICTURE_TYPE_PUBLISHER_LOGOTYPE = 20, /**< Publisher/Studio logotype */
   9.754 +	FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED
   9.755 +} FLAC__StreamMetadata_Picture_Type;
   9.756 +
   9.757 +/** Maps a FLAC__StreamMetadata_Picture_Type to a C string.
   9.758 + *
   9.759 + *  Using a FLAC__StreamMetadata_Picture_Type as the index to this array
   9.760 + *  will give the string equivalent.  The contents should not be
   9.761 + *  modified.
   9.762 + */
   9.763 +extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[];
   9.764 +
   9.765 +/** FLAC PICTURE structure.  (See the
   9.766 + * <A HREF="../format.html#metadata_block_picture">format specification</A>
   9.767 + * for the full description of each field.)
   9.768 + */
   9.769 +typedef struct {
   9.770 +	FLAC__StreamMetadata_Picture_Type type;
   9.771 +	/**< The kind of picture stored. */
   9.772 +
   9.773 +	char *mime_type;
   9.774 +	/**< Picture data's MIME type, in ASCII printable characters
   9.775 +	 * 0x20-0x7e, NUL terminated.  For best compatibility with players,
   9.776 +	 * use picture data of MIME type \c image/jpeg or \c image/png.  A
   9.777 +	 * MIME type of '-->' is also allowed, in which case the picture
   9.778 +	 * data should be a complete URL.  In file storage, the MIME type is
   9.779 +	 * stored as a 32-bit length followed by the ASCII string with no NUL
   9.780 +	 * terminator, but is converted to a plain C string in this structure
   9.781 +	 * for convenience.
   9.782 +	 */
   9.783 +
   9.784 +	FLAC__byte *description;
   9.785 +	/**< Picture's description in UTF-8, NUL terminated.  In file storage,
   9.786 +	 * the description is stored as a 32-bit length followed by the UTF-8
   9.787 +	 * string with no NUL terminator, but is converted to a plain C string
   9.788 +	 * in this structure for convenience.
   9.789 +	 */
   9.790 +
   9.791 +	FLAC__uint32 width;
   9.792 +	/**< Picture's width in pixels. */
   9.793 +
   9.794 +	FLAC__uint32 height;
   9.795 +	/**< Picture's height in pixels. */
   9.796 +
   9.797 +	FLAC__uint32 depth;
   9.798 +	/**< Picture's color depth in bits-per-pixel. */
   9.799 +
   9.800 +	FLAC__uint32 colors;
   9.801 +	/**< For indexed palettes (like GIF), picture's number of colors (the
   9.802 +	 * number of palette entries), or \c 0 for non-indexed (i.e. 2^depth).
   9.803 +	 */
   9.804 +
   9.805 +	FLAC__uint32 data_length;
   9.806 +	/**< Length of binary picture data in bytes. */
   9.807 +
   9.808 +	FLAC__byte *data;
   9.809 +	/**< Binary picture data. */
   9.810 +
   9.811 +} FLAC__StreamMetadata_Picture;
   9.812 +
   9.813 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN; /**< == 32 (bits) */
   9.814 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN; /**< == 32 (bits) */
   9.815 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN; /**< == 32 (bits) */
   9.816 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN; /**< == 32 (bits) */
   9.817 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN; /**< == 32 (bits) */
   9.818 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN; /**< == 32 (bits) */
   9.819 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN; /**< == 32 (bits) */
   9.820 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN; /**< == 32 (bits) */
   9.821 +
   9.822 +
   9.823 +/** Structure that is used when a metadata block of unknown type is loaded.
   9.824 + *  The contents are opaque.  The structure is used only internally to
   9.825 + *  correctly handle unknown metadata.
   9.826 + */
   9.827 +typedef struct {
   9.828 +	FLAC__byte *data;
   9.829 +} FLAC__StreamMetadata_Unknown;
   9.830 +
   9.831 +
   9.832 +/** FLAC metadata block structure.  (c.f. <A HREF="../format.html#metadata_block">format specification</A>)
   9.833 + */
   9.834 +typedef struct {
   9.835 +	FLAC__MetadataType type;
   9.836 +	/**< The type of the metadata block; used determine which member of the
   9.837 +	 * \a data union to dereference.  If type >= FLAC__METADATA_TYPE_UNDEFINED
   9.838 +	 * then \a data.unknown must be used. */
   9.839 +
   9.840 +	FLAC__bool is_last;
   9.841 +	/**< \c true if this metadata block is the last, else \a false */
   9.842 +
   9.843 +	unsigned length;
   9.844 +	/**< Length, in bytes, of the block data as it appears in the stream. */
   9.845 +
   9.846 +	union {
   9.847 +		FLAC__StreamMetadata_StreamInfo stream_info;
   9.848 +		FLAC__StreamMetadata_Padding padding;
   9.849 +		FLAC__StreamMetadata_Application application;
   9.850 +		FLAC__StreamMetadata_SeekTable seek_table;
   9.851 +		FLAC__StreamMetadata_VorbisComment vorbis_comment;
   9.852 +		FLAC__StreamMetadata_CueSheet cue_sheet;
   9.853 +		FLAC__StreamMetadata_Picture picture;
   9.854 +		FLAC__StreamMetadata_Unknown unknown;
   9.855 +	} data;
   9.856 +	/**< Polymorphic block data; use the \a type value to determine which
   9.857 +	 * to use. */
   9.858 +} FLAC__StreamMetadata;
   9.859 +
   9.860 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */
   9.861 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */
   9.862 +extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */
   9.863 +
   9.864 +/** The total stream length of a metadata block header in bytes. */
   9.865 +#define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
   9.866 +
   9.867 +/*****************************************************************************/
   9.868 +
   9.869 +
   9.870 +/*****************************************************************************
   9.871 + *
   9.872 + * Utility functions
   9.873 + *
   9.874 + *****************************************************************************/
   9.875 +
   9.876 +/** Tests that a sample rate is valid for FLAC.
   9.877 + *
   9.878 + * \param sample_rate  The sample rate to test for compliance.
   9.879 + * \retval FLAC__bool
   9.880 + *    \c true if the given sample rate conforms to the specification, else
   9.881 + *    \c false.
   9.882 + */
   9.883 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
   9.884 +
   9.885 +/** Tests that a sample rate is valid for the FLAC subset.  The subset rules
   9.886 + *  for valid sample rates are slightly more complex since the rate has to
   9.887 + *  be expressible completely in the frame header.
   9.888 + *
   9.889 + * \param sample_rate  The sample rate to test for compliance.
   9.890 + * \retval FLAC__bool
   9.891 + *    \c true if the given sample rate conforms to the specification for the
   9.892 + *    subset, else \c false.
   9.893 + */
   9.894 +FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate);
   9.895 +
   9.896 +/** Check a Vorbis comment entry name to see if it conforms to the Vorbis
   9.897 + *  comment specification.
   9.898 + *
   9.899 + *  Vorbis comment names must be composed only of characters from
   9.900 + *  [0x20-0x3C,0x3E-0x7D].
   9.901 + *
   9.902 + * \param name       A NUL-terminated string to be checked.
   9.903 + * \assert
   9.904 + *    \code name != NULL \endcode
   9.905 + * \retval FLAC__bool
   9.906 + *    \c false if entry name is illegal, else \c true.
   9.907 + */
   9.908 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name);
   9.909 +
   9.910 +/** Check a Vorbis comment entry value to see if it conforms to the Vorbis
   9.911 + *  comment specification.
   9.912 + *
   9.913 + *  Vorbis comment values must be valid UTF-8 sequences.
   9.914 + *
   9.915 + * \param value      A string to be checked.
   9.916 + * \param length     A the length of \a value in bytes.  May be
   9.917 + *                   \c (unsigned)(-1) to indicate that \a value is a plain
   9.918 + *                   UTF-8 NUL-terminated string.
   9.919 + * \assert
   9.920 + *    \code value != NULL \endcode
   9.921 + * \retval FLAC__bool
   9.922 + *    \c false if entry name is illegal, else \c true.
   9.923 + */
   9.924 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length);
   9.925 +
   9.926 +/** Check a Vorbis comment entry to see if it conforms to the Vorbis
   9.927 + *  comment specification.
   9.928 + *
   9.929 + *  Vorbis comment entries must be of the form 'name=value', and 'name' and
   9.930 + *  'value' must be legal according to
   9.931 + *  FLAC__format_vorbiscomment_entry_name_is_legal() and
   9.932 + *  FLAC__format_vorbiscomment_entry_value_is_legal() respectively.
   9.933 + *
   9.934 + * \param entry      An entry to be checked.
   9.935 + * \param length     The length of \a entry in bytes.
   9.936 + * \assert
   9.937 + *    \code value != NULL \endcode
   9.938 + * \retval FLAC__bool
   9.939 + *    \c false if entry name is illegal, else \c true.
   9.940 + */
   9.941 +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length);
   9.942 +
   9.943 +/** Check a seek table to see if it conforms to the FLAC specification.
   9.944 + *  See the format specification for limits on the contents of the
   9.945 + *  seek table.
   9.946 + *
   9.947 + * \param seek_table  A pointer to a seek table to be checked.
   9.948 + * \assert
   9.949 + *    \code seek_table != NULL \endcode
   9.950 + * \retval FLAC__bool
   9.951 + *    \c false if seek table is illegal, else \c true.
   9.952 + */
   9.953 +FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
   9.954 +
   9.955 +/** Sort a seek table's seek points according to the format specification.
   9.956 + *  This includes a "unique-ification" step to remove duplicates, i.e.
   9.957 + *  seek points with identical \a sample_number values.  Duplicate seek
   9.958 + *  points are converted into placeholder points and sorted to the end of
   9.959 + *  the table.
   9.960 + *
   9.961 + * \param seek_table  A pointer to a seek table to be sorted.
   9.962 + * \assert
   9.963 + *    \code seek_table != NULL \endcode
   9.964 + * \retval unsigned
   9.965 + *    The number of duplicate seek points converted into placeholders.
   9.966 + */
   9.967 +FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
   9.968 +
   9.969 +/** Check a cue sheet to see if it conforms to the FLAC specification.
   9.970 + *  See the format specification for limits on the contents of the
   9.971 + *  cue sheet.
   9.972 + *
   9.973 + * \param cue_sheet  A pointer to an existing cue sheet to be checked.
   9.974 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
   9.975 + *                   stringent requirements for a CD-DA (audio) disc.
   9.976 + * \param violation  Address of a pointer to a string.  If there is a
   9.977 + *                   violation, a pointer to a string explanation of the
   9.978 + *                   violation will be returned here. \a violation may be
   9.979 + *                   \c NULL if you don't need the returned string.  Do not
   9.980 + *                   free the returned string; it will always point to static
   9.981 + *                   data.
   9.982 + * \assert
   9.983 + *    \code cue_sheet != NULL \endcode
   9.984 + * \retval FLAC__bool
   9.985 + *    \c false if cue sheet is illegal, else \c true.
   9.986 + */
   9.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);
   9.988 +
   9.989 +/** Check picture data to see if it conforms to the FLAC specification.
   9.990 + *  See the format specification for limits on the contents of the
   9.991 + *  PICTURE block.
   9.992 + *
   9.993 + * \param picture    A pointer to existing picture data to be checked.
   9.994 + * \param violation  Address of a pointer to a string.  If there is a
   9.995 + *                   violation, a pointer to a string explanation of the
   9.996 + *                   violation will be returned here. \a violation may be
   9.997 + *                   \c NULL if you don't need the returned string.  Do not
   9.998 + *                   free the returned string; it will always point to static
   9.999 + *                   data.
  9.1000 + * \assert
  9.1001 + *    \code picture != NULL \endcode
  9.1002 + * \retval FLAC__bool
  9.1003 + *    \c false if picture data is illegal, else \c true.
  9.1004 + */
  9.1005 +FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation);
  9.1006 +
  9.1007 +/* \} */
  9.1008 +
  9.1009 +#ifdef __cplusplus
  9.1010 +}
  9.1011 +#endif
  9.1012 +
  9.1013 +#endif
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/VisualC/flac/include/FLAC/metadata.h	Sun Jan 01 14:40:22 2012 -0500
    10.3 @@ -0,0 +1,2181 @@
    10.4 +/* libFLAC - Free Lossless Audio Codec library
    10.5 + * Copyright (C) 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__METADATA_H
   10.36 +#define FLAC__METADATA_H
   10.37 +
   10.38 +#include <sys/types.h> /* for off_t */
   10.39 +#include "export.h"
   10.40 +#include "callback.h"
   10.41 +#include "format.h"
   10.42 +
   10.43 +/* --------------------------------------------------------------------
   10.44 +   (For an example of how all these routines are used, see the source
   10.45 +   code for the unit tests in src/test_libFLAC/metadata_*.c, or
   10.46 +   metaflac in src/metaflac/)
   10.47 +   ------------------------------------------------------------------*/
   10.48 +
   10.49 +/** \file include/FLAC/metadata.h
   10.50 + *
   10.51 + *  \brief
   10.52 + *  This module provides functions for creating and manipulating FLAC
   10.53 + *  metadata blocks in memory, and three progressively more powerful
   10.54 + *  interfaces for traversing and editing metadata in FLAC files.
   10.55 + *
   10.56 + *  See the detailed documentation for each interface in the
   10.57 + *  \link flac_metadata metadata \endlink module.
   10.58 + */
   10.59 +
   10.60 +/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
   10.61 + *  \ingroup flac
   10.62 + *
   10.63 + *  \brief
   10.64 + *  This module provides functions for creating and manipulating FLAC
   10.65 + *  metadata blocks in memory, and three progressively more powerful
   10.66 + *  interfaces for traversing and editing metadata in native FLAC files.
   10.67 + *  Note that currently only the Chain interface (level 2) supports Ogg
   10.68 + *  FLAC files, and it is read-only i.e. no writing back changed
   10.69 + *  metadata to file.
   10.70 + *
   10.71 + *  There are three metadata interfaces of increasing complexity:
   10.72 + *
   10.73 + *  Level 0:
   10.74 + *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
   10.75 + *  PICTURE blocks.
   10.76 + *
   10.77 + *  Level 1:
   10.78 + *  Read-write access to all metadata blocks.  This level is write-
   10.79 + *  efficient in most cases (more on this below), and uses less memory
   10.80 + *  than level 2.
   10.81 + *
   10.82 + *  Level 2:
   10.83 + *  Read-write access to all metadata blocks.  This level is write-
   10.84 + *  efficient in all cases, but uses more memory since all metadata for
   10.85 + *  the whole file is read into memory and manipulated before writing
   10.86 + *  out again.
   10.87 + *
   10.88 + *  What do we mean by efficient?  Since FLAC metadata appears at the
   10.89 + *  beginning of the file, when writing metadata back to a FLAC file
   10.90 + *  it is possible to grow or shrink the metadata such that the entire
   10.91 + *  file must be rewritten.  However, if the size remains the same during
   10.92 + *  changes or PADDING blocks are utilized, only the metadata needs to be
   10.93 + *  overwritten, which is much faster.
   10.94 + *
   10.95 + *  Efficient means the whole file is rewritten at most one time, and only
   10.96 + *  when necessary.  Level 1 is not efficient only in the case that you
   10.97 + *  cause more than one metadata block to grow or shrink beyond what can
   10.98 + *  be accomodated by padding.  In this case you should probably use level
   10.99 + *  2, which allows you to edit all the metadata for a file in memory and
  10.100 + *  write it out all at once.
  10.101 + *
  10.102 + *  All levels know how to skip over and not disturb an ID3v2 tag at the
  10.103 + *  front of the file.
  10.104 + *
  10.105 + *  All levels access files via their filenames.  In addition, level 2
  10.106 + *  has additional alternative read and write functions that take an I/O
  10.107 + *  handle and callbacks, for situations where access by filename is not
  10.108 + *  possible.
  10.109 + *
  10.110 + *  In addition to the three interfaces, this module defines functions for
  10.111 + *  creating and manipulating various metadata objects in memory.  As we see
  10.112 + *  from the Format module, FLAC metadata blocks in memory are very primitive
  10.113 + *  structures for storing information in an efficient way.  Reading
  10.114 + *  information from the structures is easy but creating or modifying them
  10.115 + *  directly is more complex.  The metadata object routines here facilitate
  10.116 + *  this by taking care of the consistency and memory management drudgery.
  10.117 + *
  10.118 + *  Unless you will be using the level 1 or 2 interfaces to modify existing
  10.119 + *  metadata however, you will not probably not need these.
  10.120 + *
  10.121 + *  From a dependency standpoint, none of the encoders or decoders require
  10.122 + *  the metadata module.  This is so that embedded users can strip out the
  10.123 + *  metadata module from libFLAC to reduce the size and complexity.
  10.124 + */
  10.125 +
  10.126 +#ifdef __cplusplus
  10.127 +extern "C" {
  10.128 +#endif
  10.129 +
  10.130 +
  10.131 +/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
  10.132 + *  \ingroup flac_metadata
  10.133 + *
  10.134 + *  \brief
  10.135 + *  The level 0 interface consists of individual routines to read the
  10.136 + *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
  10.137 + *  only a filename.
  10.138 + *
  10.139 + *  They try to skip any ID3v2 tag at the head of the file.
  10.140 + *
  10.141 + * \{
  10.142 + */
  10.143 +
  10.144 +/** Read the STREAMINFO metadata block of the given FLAC file.  This function
  10.145 + *  will try to skip any ID3v2 tag at the head of the file.
  10.146 + *
  10.147 + * \param filename    The path to the FLAC file to read.
  10.148 + * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
  10.149 + *                    FLAC__StreamMetadata is a simple structure with no
  10.150 + *                    memory allocation involved, you pass the address of
  10.151 + *                    an existing structure.  It need not be initialized.
  10.152 + * \assert
  10.153 + *    \code filename != NULL \endcode
  10.154 + *    \code streaminfo != NULL \endcode
  10.155 + * \retval FLAC__bool
  10.156 + *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
  10.157 + *    \c false if there was a memory allocation error, a file decoder error,
  10.158 + *    or the file contained no STREAMINFO block.  (A memory allocation error
  10.159 + *    is possible because this function must set up a file decoder.)
  10.160 + */
  10.161 +FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
  10.162 +
  10.163 +/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
  10.164 + *  function will try to skip any ID3v2 tag at the head of the file.
  10.165 + *
  10.166 + * \param filename    The path to the FLAC file to read.
  10.167 + * \param tags        The address where the returned pointer will be
  10.168 + *                    stored.  The \a tags object must be deleted by
  10.169 + *                    the caller using FLAC__metadata_object_delete().
  10.170 + * \assert
  10.171 + *    \code filename != NULL \endcode
  10.172 + *    \code tags != NULL \endcode
  10.173 + * \retval FLAC__bool
  10.174 + *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
  10.175 + *    and \a *tags will be set to the address of the metadata structure.
  10.176 + *    Returns \c false if there was a memory allocation error, a file
  10.177 + *    decoder error, or the file contained no VORBIS_COMMENT block, and
  10.178 + *    \a *tags will be set to \c NULL.
  10.179 + */
  10.180 +FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
  10.181 +
  10.182 +/** Read the CUESHEET metadata block of the given FLAC file.  This
  10.183 + *  function will try to skip any ID3v2 tag at the head of the file.
  10.184 + *
  10.185 + * \param filename    The path to the FLAC file to read.
  10.186 + * \param cuesheet    The address where the returned pointer will be
  10.187 + *                    stored.  The \a cuesheet object must be deleted by
  10.188 + *                    the caller using FLAC__metadata_object_delete().
  10.189 + * \assert
  10.190 + *    \code filename != NULL \endcode
  10.191 + *    \code cuesheet != NULL \endcode
  10.192 + * \retval FLAC__bool
  10.193 + *    \c true if a valid CUESHEET block was read from \a filename,
  10.194 + *    and \a *cuesheet will be set to the address of the metadata
  10.195 + *    structure.  Returns \c false if there was a memory allocation
  10.196 + *    error, a file decoder error, or the file contained no CUESHEET
  10.197 + *    block, and \a *cuesheet will be set to \c NULL.
  10.198 + */
  10.199 +FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
  10.200 +
  10.201 +/** Read a PICTURE metadata block of the given FLAC file.  This
  10.202 + *  function will try to skip any ID3v2 tag at the head of the file.
  10.203 + *  Since there can be more than one PICTURE block in a file, this
  10.204 + *  function takes a number of parameters that act as constraints to
  10.205 + *  the search.  The PICTURE block with the largest area matching all
  10.206 + *  the constraints will be returned, or \a *picture will be set to
  10.207 + *  \c NULL if there was no such block.
  10.208 + *
  10.209 + * \param filename    The path to the FLAC file to read.
  10.210 + * \param picture     The address where the returned pointer will be
  10.211 + *                    stored.  The \a picture object must be deleted by
  10.212 + *                    the caller using FLAC__metadata_object_delete().
  10.213 + * \param type        The desired picture type.  Use \c -1 to mean
  10.214 + *                    "any type".
  10.215 + * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
  10.216 + *                    string will be matched exactly.  Use \c NULL to
  10.217 + *                    mean "any MIME type".
  10.218 + * \param description The desired description.  The string will be
  10.219 + *                    matched exactly.  Use \c NULL to mean "any
  10.220 + *                    description".
  10.221 + * \param max_width   The maximum width in pixels desired.  Use
  10.222 + *                    \c (unsigned)(-1) to mean "any width".
  10.223 + * \param max_height  The maximum height in pixels desired.  Use
  10.224 + *                    \c (unsigned)(-1) to mean "any height".
  10.225 + * \param max_depth   The maximum color depth in bits-per-pixel desired.
  10.226 + *                    Use \c (unsigned)(-1) to mean "any depth".
  10.227 + * \param max_colors  The maximum number of colors desired.  Use
  10.228 + *                    \c (unsigned)(-1) to mean "any number of colors".
  10.229 + * \assert
  10.230 + *    \code filename != NULL \endcode
  10.231 + *    \code picture != NULL \endcode
  10.232 + * \retval FLAC__bool
  10.233 + *    \c true if a valid PICTURE block was read from \a filename,
  10.234 + *    and \a *picture will be set to the address of the metadata
  10.235 + *    structure.  Returns \c false if there was a memory allocation
  10.236 + *    error, a file decoder error, or the file contained no PICTURE
  10.237 + *    block, and \a *picture will be set to \c NULL.
  10.238 + */
  10.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);
  10.240 +
  10.241 +/* \} */
  10.242 +
  10.243 +
  10.244 +/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
  10.245 + *  \ingroup flac_metadata
  10.246 + *
  10.247 + * \brief
  10.248 + * The level 1 interface provides read-write access to FLAC file metadata and
  10.249 + * operates directly on the FLAC file.
  10.250 + *
  10.251 + * The general usage of this interface is:
  10.252 + *
  10.253 + * - Create an iterator using FLAC__metadata_simple_iterator_new()
  10.254 + * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
  10.255 + *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
  10.256 + *   see if the file is writable, or only read access is allowed.
  10.257 + * - Use FLAC__metadata_simple_iterator_next() and
  10.258 + *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
  10.259 + *   This is does not read the actual blocks themselves.
  10.260 + *   FLAC__metadata_simple_iterator_next() is relatively fast.
  10.261 + *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
  10.262 + *   forward from the front of the file.
  10.263 + * - Use FLAC__metadata_simple_iterator_get_block_type() or
  10.264 + *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
  10.265 + *   the current iterator position.  The returned object is yours to modify
  10.266 + *   and free.
  10.267 + * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
  10.268 + *   back.  You must have write permission to the original file.  Make sure to
  10.269 + *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
  10.270 + *   below.
  10.271 + * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
  10.272 + *   Use the object creation functions from
  10.273 + *   \link flac_metadata_object here \endlink to generate new objects.
  10.274 + * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
  10.275 + *   currently referred to by the iterator, or replace it with padding.
  10.276 + * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
  10.277 + *   finished.
  10.278 + *
  10.279 + * \note
  10.280 + * The FLAC file remains open the whole time between
  10.281 + * FLAC__metadata_simple_iterator_init() and
  10.282 + * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
  10.283 + * the file during this time.
  10.284 + *
  10.285 + * \note
  10.286 + * Do not modify the \a is_last, \a length, or \a type fields of returned
  10.287 + * FLAC__StreamMetadata objects.  These are managed automatically.
  10.288 + *
  10.289 + * \note
  10.290 + * If any of the modification functions
  10.291 + * (FLAC__metadata_simple_iterator_set_block(),
  10.292 + * FLAC__metadata_simple_iterator_delete_block(),
  10.293 + * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
  10.294 + * you should delete the iterator as it may no longer be valid.
  10.295 + *
  10.296 + * \{
  10.297 + */
  10.298 +
  10.299 +struct FLAC__Metadata_SimpleIterator;
  10.300 +/** The opaque structure definition for the level 1 iterator type.
  10.301 + *  See the
  10.302 + *  \link flac_metadata_level1 metadata level 1 module \endlink
  10.303 + *  for a detailed description.
  10.304 + */
  10.305 +typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
  10.306 +
  10.307 +/** Status type for FLAC__Metadata_SimpleIterator.
  10.308 + *
  10.309 + *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
  10.310 + */
  10.311 +typedef enum {
  10.312 +
  10.313 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
  10.314 +	/**< The iterator is in the normal OK state */
  10.315 +
  10.316 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
  10.317 +	/**< The data passed into a function violated the function's usage criteria */
  10.318 +
  10.319 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
  10.320 +	/**< The iterator could not open the target file */
  10.321 +
  10.322 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
  10.323 +	/**< The iterator could not find the FLAC signature at the start of the file */
  10.324 +
  10.325 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
  10.326 +	/**< The iterator tried to write to a file that was not writable */
  10.327 +
  10.328 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
  10.329 +	/**< The iterator encountered input that does not conform to the FLAC metadata specification */
  10.330 +
  10.331 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
  10.332 +	/**< The iterator encountered an error while reading the FLAC file */
  10.333 +
  10.334 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
  10.335 +	/**< The iterator encountered an error while seeking in the FLAC file */
  10.336 +
  10.337 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
  10.338 +	/**< The iterator encountered an error while writing the FLAC file */
  10.339 +
  10.340 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
  10.341 +	/**< The iterator encountered an error renaming the FLAC file */
  10.342 +
  10.343 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
  10.344 +	/**< The iterator encountered an error removing the temporary file */
  10.345 +
  10.346 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
  10.347 +	/**< Memory allocation failed */
  10.348 +
  10.349 +	FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
  10.350 +	/**< The caller violated an assertion or an unexpected error occurred */
  10.351 +
  10.352 +} FLAC__Metadata_SimpleIteratorStatus;
  10.353 +
  10.354 +/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
  10.355 + *
  10.356 + *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
  10.357 + *  will give the string equivalent.  The contents should not be modified.
  10.358 + */
  10.359 +extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
  10.360 +
  10.361 +
  10.362 +/** Create a new iterator instance.
  10.363 + *
  10.364 + * \retval FLAC__Metadata_SimpleIterator*
  10.365 + *    \c NULL if there was an error allocating memory, else the new instance.
  10.366 + */
  10.367 +FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
  10.368 +
  10.369 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  10.370 + *
  10.371 + * \param iterator  A pointer to an existing iterator.
  10.372 + * \assert
  10.373 + *    \code iterator != NULL \endcode
  10.374 + */
  10.375 +FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
  10.376 +
  10.377 +/** Get the current status of the iterator.  Call this after a function
  10.378 + *  returns \c false to get the reason for the error.  Also resets the status
  10.379 + *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
  10.380 + *
  10.381 + * \param iterator  A pointer to an existing iterator.
  10.382 + * \assert
  10.383 + *    \code iterator != NULL \endcode
  10.384 + * \retval FLAC__Metadata_SimpleIteratorStatus
  10.385 + *    The current status of the iterator.
  10.386 + */
  10.387 +FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
  10.388 +
  10.389 +/** Initialize the iterator to point to the first metadata block in the
  10.390 + *  given FLAC file.
  10.391 + *
  10.392 + * \param iterator             A pointer to an existing iterator.
  10.393 + * \param filename             The path to the FLAC file.
  10.394 + * \param read_only            If \c true, the FLAC file will be opened
  10.395 + *                             in read-only mode; if \c false, the FLAC
  10.396 + *                             file will be opened for edit even if no
  10.397 + *                             edits are performed.
  10.398 + * \param preserve_file_stats  If \c true, the owner and modification
  10.399 + *                             time will be preserved even if the FLAC
  10.400 + *                             file is written to.
  10.401 + * \assert
  10.402 + *    \code iterator != NULL \endcode
  10.403 + *    \code filename != NULL \endcode
  10.404 + * \retval FLAC__bool
  10.405 + *    \c false if a memory allocation error occurs, the file can't be
  10.406 + *    opened, or another error occurs, else \c true.
  10.407 + */
  10.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);
  10.409 +
  10.410 +/** Returns \c true if the FLAC file is writable.  If \c false, calls to
  10.411 + *  FLAC__metadata_simple_iterator_set_block() and
  10.412 + *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
  10.413 + *
  10.414 + * \param iterator             A pointer to an existing iterator.
  10.415 + * \assert
  10.416 + *    \code iterator != NULL \endcode
  10.417 + * \retval FLAC__bool
  10.418 + *    See above.
  10.419 + */
  10.420 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
  10.421 +
  10.422 +/** Moves the iterator forward one metadata block, returning \c false if
  10.423 + *  already at the end.
  10.424 + *
  10.425 + * \param iterator  A pointer to an existing initialized iterator.
  10.426 + * \assert
  10.427 + *    \code iterator != NULL \endcode
  10.428 + *    \a iterator has been successfully initialized with
  10.429 + *    FLAC__metadata_simple_iterator_init()
  10.430 + * \retval FLAC__bool
  10.431 + *    \c false if already at the last metadata block of the chain, else
  10.432 + *    \c true.
  10.433 + */
  10.434 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
  10.435 +
  10.436 +/** Moves the iterator backward one metadata block, returning \c false if
  10.437 + *  already at the beginning.
  10.438 + *
  10.439 + * \param iterator  A pointer to an existing initialized iterator.
  10.440 + * \assert
  10.441 + *    \code iterator != NULL \endcode
  10.442 + *    \a iterator has been successfully initialized with
  10.443 + *    FLAC__metadata_simple_iterator_init()
  10.444 + * \retval FLAC__bool
  10.445 + *    \c false if already at the first metadata block of the chain, else
  10.446 + *    \c true.
  10.447 + */
  10.448 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
  10.449 +
  10.450 +/** Returns a flag telling if the current metadata block is the last.
  10.451 + *
  10.452 + * \param iterator  A pointer to an existing initialized iterator.
  10.453 + * \assert
  10.454 + *    \code iterator != NULL \endcode
  10.455 + *    \a iterator has been successfully initialized with
  10.456 + *    FLAC__metadata_simple_iterator_init()
  10.457 + * \retval FLAC__bool
  10.458 + *    \c true if the current metadata block is the last in the file,
  10.459 + *    else \c false.
  10.460 + */
  10.461 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
  10.462 +
  10.463 +/** Get the offset of the metadata block at the current position.  This
  10.464 + *  avoids reading the actual block data which can save time for large
  10.465 + *  blocks.
  10.466 + *
  10.467 + * \param iterator  A pointer to an existing initialized iterator.
  10.468 + * \assert
  10.469 + *    \code iterator != NULL \endcode
  10.470 + *    \a iterator has been successfully initialized with
  10.471 + *    FLAC__metadata_simple_iterator_init()
  10.472 + * \retval off_t
  10.473 + *    The offset of the metadata block at the current iterator position.
  10.474 + *    This is the byte offset relative to the beginning of the file of
  10.475 + *    the current metadata block's header.
  10.476 + */
  10.477 +FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
  10.478 +
  10.479 +/** Get the type of the metadata block at the current position.  This
  10.480 + *  avoids reading the actual block data which can save time for large
  10.481 + *  blocks.
  10.482 + *
  10.483 + * \param iterator  A pointer to an existing initialized iterator.
  10.484 + * \assert
  10.485 + *    \code iterator != NULL \endcode
  10.486 + *    \a iterator has been successfully initialized with
  10.487 + *    FLAC__metadata_simple_iterator_init()
  10.488 + * \retval FLAC__MetadataType
  10.489 + *    The type of the metadata block at the current iterator position.
  10.490 + */
  10.491 +FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
  10.492 +
  10.493 +/** Get the length of the metadata block at the current position.  This
  10.494 + *  avoids reading the actual block data which can save time for large
  10.495 + *  blocks.
  10.496 + *
  10.497 + * \param iterator  A pointer to an existing initialized iterator.
  10.498 + * \assert
  10.499 + *    \code iterator != NULL \endcode
  10.500 + *    \a iterator has been successfully initialized with
  10.501 + *    FLAC__metadata_simple_iterator_init()
  10.502 + * \retval unsigned
  10.503 + *    The length of the metadata block at the current iterator position.
  10.504 + *    The is same length as that in the
  10.505 + *    <a href="http://flac.sourceforge.net/format.html#metadata_block_header">metadata block header</a>,
  10.506 + *    i.e. the length of the metadata body that follows the header.
  10.507 + */
  10.508 +FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
  10.509 +
  10.510 +/** Get the application ID of the \c APPLICATION block at the current
  10.511 + *  position.  This avoids reading the actual block data which can save
  10.512 + *  time for large blocks.
  10.513 + *
  10.514 + * \param iterator  A pointer to an existing initialized iterator.
  10.515 + * \param id        A pointer to a buffer of at least \c 4 bytes where
  10.516 + *                  the ID will be stored.
  10.517 + * \assert
  10.518 + *    \code iterator != NULL \endcode
  10.519 + *    \code id != NULL \endcode
  10.520 + *    \a iterator has been successfully initialized with
  10.521 + *    FLAC__metadata_simple_iterator_init()
  10.522 + * \retval FLAC__bool
  10.523 + *    \c true if the ID was successfully read, else \c false, in which
  10.524 + *    case you should check FLAC__metadata_simple_iterator_status() to
  10.525 + *    find out why.  If the status is
  10.526 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the
  10.527 + *    current metadata block is not an \c APPLICATION block.  Otherwise
  10.528 + *    if the status is
  10.529 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or
  10.530 + *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error
  10.531 + *    occurred and the iterator can no longer be used.
  10.532 + */
  10.533 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
  10.534 +
  10.535 +/** Get the metadata block at the current position.  You can modify the
  10.536 + *  block but must use FLAC__metadata_simple_iterator_set_block() to
  10.537 + *  write it back to the FLAC file.
  10.538 + *
  10.539 + *  You must call FLAC__metadata_object_delete() on the returned object
  10.540 + *  when you are finished with it.
  10.541 + *
  10.542 + * \param iterator  A pointer to an existing initialized iterator.
  10.543 + * \assert
  10.544 + *    \code iterator != NULL \endcode
  10.545 + *    \a iterator has been successfully initialized with
  10.546 + *    FLAC__metadata_simple_iterator_init()
  10.547 + * \retval FLAC__StreamMetadata*
  10.548 + *    The current metadata block, or \c NULL if there was a memory
  10.549 + *    allocation error.
  10.550 + */
  10.551 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
  10.552 +
  10.553 +/** Write a block back to the FLAC file.  This function tries to be
  10.554 + *  as efficient as possible; how the block is actually written is
  10.555 + *  shown by the following:
  10.556 + *
  10.557 + *  Existing block is a STREAMINFO block and the new block is a
  10.558 + *  STREAMINFO block: the new block is written in place.  Make sure
  10.559 + *  you know what you're doing when changing the values of a
  10.560 + *  STREAMINFO block.
  10.561 + *
  10.562 + *  Existing block is a STREAMINFO block and the new block is a
  10.563 + *  not a STREAMINFO block: this is an error since the first block
  10.564 + *  must be a STREAMINFO block.  Returns \c false without altering the
  10.565 + *  file.
  10.566 + *
  10.567 + *  Existing block is not a STREAMINFO block and the new block is a
  10.568 + *  STREAMINFO block: this is an error since there may be only one
  10.569 + *  STREAMINFO block.  Returns \c false without altering the file.
  10.570 + *
  10.571 + *  Existing block and new block are the same length: the existing
  10.572 + *  block will be replaced by the new block, written in place.
  10.573 + *
  10.574 + *  Existing block is longer than new block: if use_padding is \c true,
  10.575 + *  the existing block will be overwritten in place with the new
  10.576 + *  block followed by a PADDING block, if possible, to make the total
  10.577 + *  size the same as the existing block.  Remember that a padding
  10.578 + *  block requires at least four bytes so if the difference in size
  10.579 + *  between the new block and existing block is less than that, the
  10.580 + *  entire file will have to be rewritten, using the new block's
  10.581 + *  exact size.  If use_padding is \c false, the entire file will be
  10.582 + *  rewritten, replacing the existing block by the new block.
  10.583 + *
  10.584 + *  Existing block is shorter than new block: if use_padding is \c true,
  10.585 + *  the function will try and expand the new block into the following
  10.586 + *  PADDING block, if it exists and doing so won't shrink the PADDING
  10.587 + *  block to less than 4 bytes.  If there is no following PADDING
  10.588 + *  block, or it will shrink to less than 4 bytes, or use_padding is
  10.589 + *  \c false, the entire file is rewritten, replacing the existing block
  10.590 + *  with the new block.  Note that in this case any following PADDING
  10.591 + *  block is preserved as is.
  10.592 + *
  10.593 + *  After writing the block, the iterator will remain in the same
  10.594 + *  place, i.e. pointing to the new block.
  10.595 + *
  10.596 + * \param iterator     A pointer to an existing initialized iterator.
  10.597 + * \param block        The block to set.
  10.598 + * \param use_padding  See above.
  10.599 + * \assert
  10.600 + *    \code iterator != NULL \endcode
  10.601 + *    \a iterator has been successfully initialized with
  10.602 + *    FLAC__metadata_simple_iterator_init()
  10.603 + *    \code block != NULL \endcode
  10.604 + * \retval FLAC__bool
  10.605 + *    \c true if successful, else \c false.
  10.606 + */
  10.607 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  10.608 +
  10.609 +/** This is similar to FLAC__metadata_simple_iterator_set_block()
  10.610 + *  except that instead of writing over an existing block, it appends
  10.611 + *  a block after the existing block.  \a use_padding is again used to
  10.612 + *  tell the function to try an expand into following padding in an
  10.613 + *  attempt to avoid rewriting the entire file.
  10.614 + *
  10.615 + *  This function will fail and return \c false if given a STREAMINFO
  10.616 + *  block.
  10.617 + *
  10.618 + *  After writing the block, the iterator will be pointing to the
  10.619 + *  new block.
  10.620 + *
  10.621 + * \param iterator     A pointer to an existing initialized iterator.
  10.622 + * \param block        The block to set.
  10.623 + * \param use_padding  See above.
  10.624 + * \assert
  10.625 + *    \code iterator != NULL \endcode
  10.626 + *    \a iterator has been successfully initialized with
  10.627 + *    FLAC__metadata_simple_iterator_init()
  10.628 + *    \code block != NULL \endcode
  10.629 + * \retval FLAC__bool
  10.630 + *    \c true if successful, else \c false.
  10.631 + */
  10.632 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  10.633 +
  10.634 +/** Deletes the block at the current position.  This will cause the
  10.635 + *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
  10.636 + *  in which case the block will be replaced by an equal-sized PADDING
  10.637 + *  block.  The iterator will be left pointing to the block before the
  10.638 + *  one just deleted.
  10.639 + *
  10.640 + *  You may not delete the STREAMINFO block.
  10.641 + *
  10.642 + * \param iterator     A pointer to an existing initialized iterator.
  10.643 + * \param use_padding  See above.
  10.644 + * \assert
  10.645 + *    \code iterator != NULL \endcode
  10.646 + *    \a iterator has been successfully initialized with
  10.647 + *    FLAC__metadata_simple_iterator_init()
  10.648 + * \retval FLAC__bool
  10.649 + *    \c true if successful, else \c false.
  10.650 + */
  10.651 +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
  10.652 +
  10.653 +/* \} */
  10.654 +
  10.655 +
  10.656 +/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
  10.657 + *  \ingroup flac_metadata
  10.658 + *
  10.659 + * \brief
  10.660 + * The level 2 interface provides read-write access to FLAC file metadata;
  10.661 + * all metadata is read into memory, operated on in memory, and then written
  10.662 + * to file, which is more efficient than level 1 when editing multiple blocks.
  10.663 + *
  10.664 + * Currently Ogg FLAC is supported for read only, via
  10.665 + * FLAC__metadata_chain_read_ogg() but a subsequent
  10.666 + * FLAC__metadata_chain_write() will fail.
  10.667 + *
  10.668 + * The general usage of this interface is:
  10.669 + *
  10.670 + * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
  10.671 + *   linked list of FLAC metadata blocks.
  10.672 + * - Read all metadata into the the chain from a FLAC file using
  10.673 + *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
  10.674 + *   check the status.
  10.675 + * - Optionally, consolidate the padding using
  10.676 + *   FLAC__metadata_chain_merge_padding() or
  10.677 + *   FLAC__metadata_chain_sort_padding().
  10.678 + * - Create a new iterator using FLAC__metadata_iterator_new()
  10.679 + * - Initialize the iterator to point to the first element in the chain
  10.680 + *   using FLAC__metadata_iterator_init()
  10.681 + * - Traverse the chain using FLAC__metadata_iterator_next and
  10.682 + *   FLAC__metadata_iterator_prev().
  10.683 + * - Get a block for reading or modification using
  10.684 + *   FLAC__metadata_iterator_get_block().  The pointer to the object
  10.685 + *   inside the chain is returned, so the block is yours to modify.
  10.686 + *   Changes will be reflected in the FLAC file when you write the
  10.687 + *   chain.  You can also add and delete blocks (see functions below).
  10.688 + * - When done, write out the chain using FLAC__metadata_chain_write().
  10.689 + *   Make sure to read the whole comment to the function below.
  10.690 + * - Delete the chain using FLAC__metadata_chain_delete().
  10.691 + *
  10.692 + * \note
  10.693 + * Even though the FLAC file is not open while the chain is being
  10.694 + * manipulated, you must not alter the file externally during
  10.695 + * this time.  The chain assumes the FLAC file will not change
  10.696 + * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
  10.697 + * and FLAC__metadata_chain_write().
  10.698 + *
  10.699 + * \note
  10.700 + * Do not modify the is_last, length, or type fields of returned
  10.701 + * FLAC__StreamMetadata objects.  These are managed automatically.
  10.702 + *
  10.703 + * \note
  10.704 + * The metadata objects returned by FLAC__metadata_iterator_get_block()
  10.705 + * are owned by the chain; do not FLAC__metadata_object_delete() them.
  10.706 + * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
  10.707 + * become owned by the chain and they will be deleted when the chain is
  10.708 + * deleted.
  10.709 + *
  10.710 + * \{
  10.711 + */
  10.712 +
  10.713 +struct FLAC__Metadata_Chain;
  10.714 +/** The opaque structure definition for the level 2 chain type.
  10.715 + */
  10.716 +typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
  10.717 +
  10.718 +struct FLAC__Metadata_Iterator;
  10.719 +/** The opaque structure definition for the level 2 iterator type.
  10.720 + */
  10.721 +typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
  10.722 +
  10.723 +typedef enum {
  10.724 +	FLAC__METADATA_CHAIN_STATUS_OK = 0,
  10.725 +	/**< The chain is in the normal OK state */
  10.726 +
  10.727 +	FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
  10.728 +	/**< The data passed into a function violated the function's usage criteria */
  10.729 +
  10.730 +	FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
  10.731 +	/**< The chain could not open the target file */
  10.732 +
  10.733 +	FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
  10.734 +	/**< The chain could not find the FLAC signature at the start of the file */
  10.735 +
  10.736 +	FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
  10.737 +	/**< The chain tried to write to a file that was not writable */
  10.738 +
  10.739 +	FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
  10.740 +	/**< The chain encountered input that does not conform to the FLAC metadata specification */
  10.741 +
  10.742 +	FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
  10.743 +	/**< The chain encountered an error while reading the FLAC file */
  10.744 +
  10.745 +	FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
  10.746 +	/**< The chain encountered an error while seeking in the FLAC file */
  10.747 +
  10.748 +	FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
  10.749 +	/**< The chain encountered an error while writing the FLAC file */
  10.750 +
  10.751 +	FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
  10.752 +	/**< The chain encountered an error renaming the FLAC file */
  10.753 +
  10.754 +	FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
  10.755 +	/**< The chain encountered an error removing the temporary file */
  10.756 +
  10.757 +	FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
  10.758 +	/**< Memory allocation failed */
  10.759 +
  10.760 +	FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
  10.761 +	/**< The caller violated an assertion or an unexpected error occurred */
  10.762 +
  10.763 +	FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
  10.764 +	/**< One or more of the required callbacks was NULL */
  10.765 +
  10.766 +	FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
  10.767 +	/**< FLAC__metadata_chain_write() was called on a chain read by
  10.768 +	 *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  10.769 +	 *   or 
  10.770 +	 *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
  10.771 +	 *   was called on a chain read by
  10.772 +	 *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  10.773 +	 *   Matching read/write methods must always be used. */
  10.774 +
  10.775 +	FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
  10.776 +	/**< FLAC__metadata_chain_write_with_callbacks() was called when the
  10.777 +	 *   chain write requires a tempfile; use
  10.778 +	 *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
  10.779 +	 *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
  10.780 +	 *   called when the chain write does not require a tempfile; use
  10.781 +	 *   FLAC__metadata_chain_write_with_callbacks() instead.
  10.782 +	 *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
  10.783 +	 *   before writing via callbacks. */
  10.784 +
  10.785 +} FLAC__Metadata_ChainStatus;
  10.786 +
  10.787 +/** Maps a FLAC__Metadata_ChainStatus to a C string.
  10.788 + *
  10.789 + *  Using a FLAC__Metadata_ChainStatus as the index to this array
  10.790 + *  will give the string equivalent.  The contents should not be modified.
  10.791 + */
  10.792 +extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
  10.793 +
  10.794 +/*********** FLAC__Metadata_Chain ***********/
  10.795 +
  10.796 +/** Create a new chain instance.
  10.797 + *
  10.798 + * \retval FLAC__Metadata_Chain*
  10.799 + *    \c NULL if there was an error allocating memory, else the new instance.
  10.800 + */
  10.801 +FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
  10.802 +
  10.803 +/** Free a chain instance.  Deletes the object pointed to by \a chain.
  10.804 + *
  10.805 + * \param chain  A pointer to an existing chain.
  10.806 + * \assert
  10.807 + *    \code chain != NULL \endcode
  10.808 + */
  10.809 +FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
  10.810 +
  10.811 +/** Get the current status of the chain.  Call this after a function
  10.812 + *  returns \c false to get the reason for the error.  Also resets the
  10.813 + *  status to FLAC__METADATA_CHAIN_STATUS_OK.
  10.814 + *
  10.815 + * \param chain    A pointer to an existing chain.
  10.816 + * \assert
  10.817 + *    \code chain != NULL \endcode
  10.818 + * \retval FLAC__Metadata_ChainStatus
  10.819 + *    The current status of the chain.
  10.820 + */
  10.821 +FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
  10.822 +
  10.823 +/** Read all metadata from a FLAC file into the chain.
  10.824 + *
  10.825 + * \param chain    A pointer to an existing chain.
  10.826 + * \param filename The path to the FLAC file to read.
  10.827 + * \assert
  10.828 + *    \code chain != NULL \endcode
  10.829 + *    \code filename != NULL \endcode
  10.830 + * \retval FLAC__bool
  10.831 + *    \c true if a valid list of metadata blocks was read from
  10.832 + *    \a filename, else \c false.  On failure, check the status with
  10.833 + *    FLAC__metadata_chain_status().
  10.834 + */
  10.835 +FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
  10.836 +
  10.837 +/** Read all metadata from an Ogg FLAC file into the chain.
  10.838 + *
  10.839 + * \note Ogg FLAC metadata data writing is not supported yet and
  10.840 + * FLAC__metadata_chain_write() will fail.
  10.841 + *
  10.842 + * \param chain    A pointer to an existing chain.
  10.843 + * \param filename The path to the Ogg FLAC file to read.
  10.844 + * \assert
  10.845 + *    \code chain != NULL \endcode
  10.846 + *    \code filename != NULL \endcode
  10.847 + * \retval FLAC__bool
  10.848 + *    \c true if a valid list of metadata blocks was read from
  10.849 + *    \a filename, else \c false.  On failure, check the status with
  10.850 + *    FLAC__metadata_chain_status().
  10.851 + */
  10.852 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
  10.853 +
  10.854 +/** Read all metadata from a FLAC stream into the chain via I/O callbacks.
  10.855 + *
  10.856 + *  The \a handle need only be open for reading, but must be seekable.
  10.857 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  10.858 + *  for Windows).
  10.859 + *
  10.860 + * \param chain    A pointer to an existing chain.
  10.861 + * \param handle   The I/O handle of the FLAC stream to read.  The
  10.862 + *                 handle will NOT be closed after the metadata is read;
  10.863 + *                 that is the duty of the caller.
  10.864 + * \param callbacks
  10.865 + *                 A set of callbacks to use for I/O.  The mandatory
  10.866 + *                 callbacks are \a read, \a seek, and \a tell.
  10.867 + * \assert
  10.868 + *    \code chain != NULL \endcode
  10.869 + * \retval FLAC__bool
  10.870 + *    \c true if a valid list of metadata blocks was read from
  10.871 + *    \a handle, else \c false.  On failure, check the status with
  10.872 + *    FLAC__metadata_chain_status().
  10.873 + */
  10.874 +FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  10.875 +
  10.876 +/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
  10.877 + *
  10.878 + *  The \a handle need only be open for reading, but must be seekable.
  10.879 + *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  10.880 + *  for Windows).
  10.881 + *
  10.882 + * \note Ogg FLAC metadata data writing is not supported yet and
  10.883 + * FLAC__metadata_chain_write() will fail.
  10.884 + *
  10.885 + * \param chain    A pointer to an existing chain.
  10.886 + * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
  10.887 + *                 handle will NOT be closed after the metadata is read;
  10.888 + *                 that is the duty of the caller.
  10.889 + * \param callbacks
  10.890 + *                 A set of callbacks to use for I/O.  The mandatory
  10.891 + *                 callbacks are \a read, \a seek, and \a tell.
  10.892 + * \assert
  10.893 + *    \code chain != NULL \endcode
  10.894 + * \retval FLAC__bool
  10.895 + *    \c true if a valid list of metadata blocks was read from
  10.896 + *    \a handle, else \c false.  On failure, check the status with
  10.897 + *    FLAC__metadata_chain_status().
  10.898 + */
  10.899 +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  10.900 +
  10.901 +/** Checks if writing the given chain would require the use of a
  10.902 + *  temporary file, or if it could be written in place.
  10.903 + *
  10.904 + *  Under certain conditions, padding can be utilized so that writing
  10.905 + *  edited metadata back to the FLAC file does not require rewriting the
  10.906 + *  entire file.  If rewriting is required, then a temporary workfile is
  10.907 + *  required.  When writing metadata using callbacks, you must check
  10.908 + *  this function to know whether to call
  10.909 + *  FLAC__metadata_chain_write_with_callbacks() or
  10.910 + *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
  10.911 + *  writing with FLAC__metadata_chain_write(), the temporary file is
  10.912 + *  handled internally.
  10.913 + *
  10.914 + * \param chain    A pointer to an existing chain.
  10.915 + * \param use_padding
  10.916 + *                 Whether or not padding will be allowed to be used
  10.917 + *                 during the write.  The value of \a use_padding given
  10.918 + *                 here must match the value later passed to
  10.919 + *                 FLAC__metadata_chain_write_with_callbacks() or
  10.920 + *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
  10.921 + * \assert
  10.922 + *    \code chain != NULL \endcode
  10.923 + * \retval FLAC__bool
  10.924 + *    \c true if writing the current chain would require a tempfile, or
  10.925 + *    \c false if metadata can be written in place.
  10.926 + */
  10.927 +FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
  10.928 +
  10.929 +/** Write all metadata out to the FLAC file.  This function tries to be as
  10.930 + *  efficient as possible; how the metadata is actually written is shown by
  10.931 + *  the following:
  10.932 + *
  10.933 + *  If the current chain is the same size as the existing metadata, the new
  10.934 + *  data is written in place.
  10.935 + *
  10.936 + *  If the current chain is longer than the existing metadata, and
  10.937 + *  \a use_padding is \c true, and the last block is a PADDING block of
  10.938 + *  sufficient length, the function will truncate the final padding block
  10.939 + *  so that the overall size of the metadata is the same as the existing
  10.940 + *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
  10.941 + *  the above conditions are met, the entire FLAC file must be rewritten.
  10.942 + *  If you want to use padding this way it is a good idea to call
  10.943 + *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
  10.944 + *  amount of padding to work with, unless you need to preserve ordering
  10.945 + *  of the PADDING blocks for some reason.
  10.946 + *
  10.947 + *  If the current chain is shorter than the existing metadata, and
  10.948 + *  \a use_padding is \c true, and the final block is a PADDING block, the padding
  10.949 + *  is extended to make the overall size the same as the existing data.  If
  10.950 + *  \a use_padding is \c true and the last block is not a PADDING block, a new
  10.951 + *  PADDING block is added to the end of the new data to make it the same
  10.952 + *  size as the existing data (if possible, see the note to
  10.953 + *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
  10.954 + *  and the new data is written in place.  If none of the above apply or
  10.955 + *  \a use_padding is \c false, the entire FLAC file is rewritten.
  10.956 + *
  10.957 + *  If \a preserve_file_stats is \c true, the owner and modification time will
  10.958 + *  be preserved even if the FLAC file is written.
  10.959 + *
  10.960 + *  For this write function to be used, the chain must have been read with
  10.961 + *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
  10.962 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
  10.963 + *
  10.964 + * \param chain               A pointer to an existing chain.
  10.965 + * \param use_padding         See above.
  10.966 + * \param preserve_file_stats See above.
  10.967 + * \assert
  10.968 + *    \code chain != NULL \endcode
  10.969 + * \retval FLAC__bool
  10.970 + *    \c true if the write succeeded, else \c false.  On failure,
  10.971 + *    check the status with FLAC__metadata_chain_status().
  10.972 + */
  10.973 +FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
  10.974 +
  10.975 +/** Write all metadata out to a FLAC stream via callbacks.
  10.976 + *
  10.977 + *  (See FLAC__metadata_chain_write() for the details on how padding is
  10.978 + *  used to write metadata in place if possible.)
  10.979 + *
  10.980 + *  The \a handle must be open for updating and be seekable.  The
  10.981 + *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
  10.982 + *  for Windows).
  10.983 + *
  10.984 + *  For this write function to be used, the chain must have been read with
  10.985 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  10.986 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  10.987 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  10.988 + *  \c false.
  10.989 + *
  10.990 + * \param chain        A pointer to an existing chain.
  10.991 + * \param use_padding  See FLAC__metadata_chain_write()
  10.992 + * \param handle       The I/O handle of the FLAC stream to write.  The
  10.993 + *                     handle will NOT be closed after the metadata is
  10.994 + *                     written; that is the duty of the caller.
  10.995 + * \param callbacks    A set of callbacks to use for I/O.  The mandatory
  10.996 + *                     callbacks are \a write and \a seek.
  10.997 + * \assert
  10.998 + *    \code chain != NULL \endcode
  10.999 + * \retval FLAC__bool
 10.1000 + *    \c true if the write succeeded, else \c false.  On failure,
 10.1001 + *    check the status with FLAC__metadata_chain_status().
 10.1002 + */
 10.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);
 10.1004 +
 10.1005 +/** Write all metadata out to a FLAC stream via callbacks.
 10.1006 + *
 10.1007 + *  (See FLAC__metadata_chain_write() for the details on how padding is
 10.1008 + *  used to write metadata in place if possible.)
 10.1009 + *
 10.1010 + *  This version of the write-with-callbacks function must be used when
 10.1011 + *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
 10.1012 + *  this function, you must supply an I/O handle corresponding to the
 10.1013 + *  FLAC file to edit, and a temporary handle to which the new FLAC
 10.1014 + *  file will be written.  It is the caller's job to move this temporary
 10.1015 + *  FLAC file on top of the original FLAC file to complete the metadata
 10.1016 + *  edit.
 10.1017 + *
 10.1018 + *  The \a handle must be open for reading and be seekable.  The
 10.1019 + *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
 10.1020 + *  for Windows).
 10.1021 + *
 10.1022 + *  The \a temp_handle must be open for writing.  The
 10.1023 + *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
 10.1024 + *  for Windows).  It should be an empty stream, or at least positioned
 10.1025 + *  at the start-of-file (in which case it is the caller's duty to
 10.1026 + *  truncate it on return).
 10.1027 + *
 10.1028 + *  For this write function to be used, the chain must have been read with
 10.1029 + *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
 10.1030 + *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
 10.1031 + *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
 10.1032 + *  \c true.
 10.1033 + *
 10.1034 + * \param chain        A pointer to an existing chain.
 10.1035 + * \param use_padding  See FLAC__metadata_chain_write()
 10.1036 + * \param handle       The I/O handle of the original FLAC stream to read.
 10.1037 + *                     The handle will NOT be closed after the metadata is
 10.1038 + *                     written; that is the duty of the caller.
 10.1039 + * \param callbacks    A set of callbacks to use for I/O on \a handle.
 10.1040 + *                     The mandatory callbacks are \a read, \a seek, and
 10.1041 + *                     \a eof.
 10.1042 + * \param temp_handle  The I/O handle of the FLAC stream to write.  The
 10.1043 + *                     handle will NOT be closed after the metadata is
 10.1044 + *                     written; that is the duty of the caller.
 10.1045 + * \param temp_callbacks
 10.1046 + *                     A set of callbacks to use for I/O on temp_handle.
 10.1047 + *                     The only mandatory callback is \a write.
 10.1048 + * \assert
 10.1049 + *    \code chain != NULL \endcode
 10.1050 + * \retval FLAC__bool
 10.1051 + *    \c true if the write succeeded, else \c false.  On failure,
 10.1052 + *    check the status with FLAC__metadata_chain_status().
 10.1053 + */
 10.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);
 10.1055 +
 10.1056 +/** Merge adjacent PADDING blocks into a single block.
 10.1057 + *
 10.1058 + * \note This function does not write to the FLAC file, it only
 10.1059 + * modifies the chain.
 10.1060 + *
 10.1061 + * \warning Any iterator on the current chain will become invalid after this
 10.1062 + * call.  You should delete the iterator and get a new one.
 10.1063 + *
 10.1064 + * \param chain               A pointer to an existing chain.
 10.1065 + * \assert
 10.1066 + *    \code chain != NULL \endcode
 10.1067 + */
 10.1068 +FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
 10.1069 +
 10.1070 +/** This function will move all PADDING blocks to the end on the metadata,
 10.1071 + *  then merge them into a single block.
 10.1072 + *
 10.1073 + * \note This function does not write to the FLAC file, it only
 10.1074 + * modifies the chain.
 10.1075 + *
 10.1076 + * \warning Any iterator on the current chain will become invalid after this
 10.1077 + * call.  You should delete the iterator and get a new one.
 10.1078 + *
 10.1079 + * \param chain  A pointer to an existing chain.
 10.1080 + * \assert
 10.1081 + *    \code chain != NULL \endcode
 10.1082 + */
 10.1083 +FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
 10.1084 +
 10.1085 +
 10.1086 +/*********** FLAC__Metadata_Iterator ***********/
 10.1087 +
 10.1088 +/** Create a new iterator instance.
 10.1089 + *
 10.1090 + * \retval FLAC__Metadata_Iterator*
 10.1091 + *    \c NULL if there was an error allocating memory, else the new instance.
 10.1092 + */
 10.1093 +FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
 10.1094 +
 10.1095 +/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
 10.1096 + *
 10.1097 + * \param iterator  A pointer to an existing iterator.
 10.1098 + * \assert
 10.1099 + *    \code iterator != NULL \endcode
 10.1100 + */
 10.1101 +FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
 10.1102 +
 10.1103 +/** Initialize the iterator to point to the first metadata block in the
 10.1104 + *  given chain.
 10.1105 + *
 10.1106 + * \param iterator  A pointer to an existing iterator.
 10.1107 + * \param chain     A pointer to an existing and initialized (read) chain.
 10.1108 + * \assert
 10.1109 + *    \code iterator != NULL \endcode
 10.1110 + *    \code chain != NULL \endcode
 10.1111 + */
 10.1112 +FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
 10.1113 +
 10.1114 +/** Moves the iterator forward one metadata block, returning \c false if
 10.1115 + *  already at the end.
 10.1116 + *
 10.1117 + * \param iterator  A pointer to an existing initialized iterator.
 10.1118 + * \assert
 10.1119 + *    \code iterator != NULL \endcode
 10.1120 + *    \a iterator has been successfully initialized with
 10.1121 + *    FLAC__metadata_iterator_init()
 10.1122 + * \retval FLAC__bool
 10.1123 + *    \c false if already at the last metadata block of the chain, else
 10.1124 + *    \c true.
 10.1125 + */
 10.1126 +FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
 10.1127 +
 10.1128 +/** Moves the iterator backward one metadata block, returning \c false if
 10.1129 + *  already at the beginning.
 10.1130 + *
 10.1131 + * \param iterator  A pointer to an existing initialized iterator.
 10.1132 + * \assert
 10.1133 + *    \code iterator != NULL \endcode
 10.1134 + *    \a iterator has been successfully initialized with
 10.1135 + *    FLAC__metadata_iterator_init()
 10.1136 + * \retval FLAC__bool
 10.1137 + *    \c false if already at the first metadata block of the chain, else
 10.1138 + *    \c true.
 10.1139 + */
 10.1140 +FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
 10.1141 +
 10.1142 +/** Get the type of the metadata block at the current position.
 10.1143 + *
 10.1144 + * \param iterator  A pointer to an existing initialized iterator.
 10.1145 + * \assert
 10.1146 + *    \code iterator != NULL \endcode
 10.1147 + *    \a iterator has been successfully initialized with
 10.1148 + *    FLAC__metadata_iterator_init()
 10.1149 + * \retval FLAC__MetadataType
 10.1150 + *    The type of the metadata block at the current iterator position.
 10.1151 + */
 10.1152 +FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
 10.1153 +
 10.1154 +/** Get the metadata block at the current position.  You can modify
 10.1155 + *  the block in place but must write the chain before the changes
 10.1156 + *  are reflected to the FLAC file.  You do not need to call
 10.1157 + *  FLAC__metadata_iterator_set_block() to reflect the changes;
 10.1158 + *  the pointer returned by FLAC__metadata_iterator_get_block()
 10.1159 + *  points directly into the chain.
 10.1160 + *
 10.1161 + * \warning
 10.1162 + * Do not call FLAC__metadata_object_delete() on the returned object;
 10.1163 + * to delete a block use FLAC__metadata_iterator_delete_block().
 10.1164 + *
 10.1165 + * \param iterator  A pointer to an existing initialized iterator.
 10.1166 + * \assert
 10.1167 + *    \code iterator != NULL \endcode
 10.1168 + *    \a iterator has been successfully initialized with
 10.1169 + *    FLAC__metadata_iterator_init()
 10.1170 + * \retval FLAC__StreamMetadata*
 10.1171 + *    The current metadata block.
 10.1172 + */
 10.1173 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
 10.1174 +
 10.1175 +/** Set the metadata block at the current position, replacing the existing
 10.1176 + *  block.  The new block passed in becomes owned by the chain and it will be
 10.1177 + *  deleted when the chain is deleted.
 10.1178 + *
 10.1179 + * \param iterator  A pointer to an existing initialized iterator.
 10.1180 + * \param block     A pointer to a metadata block.
 10.1181 + * \assert
 10.1182 + *    \code iterator != NULL \endcode
 10.1183 + *    \a iterator has been successfully initialized with
 10.1184 + *    FLAC__metadata_iterator_init()
 10.1185 + *    \code block != NULL \endcode
 10.1186 + * \retval FLAC__bool
 10.1187 + *    \c false if the conditions in the above description are not met, or
 10.1188 + *    a memory allocation error occurs, otherwise \c true.
 10.1189 + */
 10.1190 +FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 10.1191 +
 10.1192 +/** Removes the current block from the chain.  If \a replace_with_padding is
 10.1193 + *  \c true, the block will instead be replaced with a padding block of equal
 10.1194 + *  size.  You can not delete the STREAMINFO block.  The iterator will be
 10.1195 + *  left pointing to the block before the one just "deleted", even if
 10.1196 + *  \a replace_with_padding is \c true.
 10.1197 + *
 10.1198 + * \param iterator              A pointer to an existing initialized iterator.
 10.1199 + * \param replace_with_padding  See above.
 10.1200 + * \assert
 10.1201 + *    \code iterator != NULL \endcode
 10.1202 + *    \a iterator has been successfully initialized with
 10.1203 + *    FLAC__metadata_iterator_init()
 10.1204 + * \retval FLAC__bool
 10.1205 + *    \c false if the conditions in the above description are not met,
 10.1206 + *    otherwise \c true.
 10.1207 + */
 10.1208 +FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
 10.1209 +
 10.1210 +/** Insert a new block before the current block.  You cannot insert a block
 10.1211 + *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
 10.1212 + *  as there can be only one, the one that already exists at the head when you
 10.1213 + *  read in a chain.  The chain takes ownership of the new block and it will be
 10.1214 + *  deleted when the chain is deleted.  The iterator will be left pointing to
 10.1215 + *  the new block.
 10.1216 + *
 10.1217 + * \param iterator  A pointer to an existing initialized iterator.
 10.1218 + * \param block     A pointer to a metadata block to insert.
 10.1219 + * \assert
 10.1220 + *    \code iterator != NULL \endcode
 10.1221 + *    \a iterator has been successfully initialized with
 10.1222 + *    FLAC__metadata_iterator_init()
 10.1223 + * \retval FLAC__bool
 10.1224 + *    \c false if the conditions in the above description are not met, or
 10.1225 + *    a memory allocation error occurs, otherwise \c true.
 10.1226 + */
 10.1227 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 10.1228 +
 10.1229 +/** Insert a new block after the current block.  You cannot insert a STREAMINFO
 10.1230 + *  block as there can be only one, the one that already exists at the head when
 10.1231 + *  you read in a chain.  The chain takes ownership of the new block and it will
 10.1232 + *  be deleted when the chain is deleted.  The iterator will be left pointing to
 10.1233 + *  the new block.
 10.1234 + *
 10.1235 + * \param iterator  A pointer to an existing initialized iterator.
 10.1236 + * \param block     A pointer to a metadata block to insert.
 10.1237 + * \assert
 10.1238 + *    \code iterator != NULL \endcode
 10.1239 + *    \a iterator has been successfully initialized with
 10.1240 + *    FLAC__metadata_iterator_init()
 10.1241 + * \retval FLAC__bool
 10.1242 + *    \c false if the conditions in the above description are not met, or
 10.1243 + *    a memory allocation error occurs, otherwise \c true.
 10.1244 + */
 10.1245 +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
 10.1246 +
 10.1247 +/* \} */
 10.1248 +
 10.1249 +
 10.1250 +/** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
 10.1251 + *  \ingroup flac_metadata
 10.1252 + *
 10.1253 + * \brief
 10.1254 + * This module contains methods for manipulating FLAC metadata objects.
 10.1255 + *
 10.1256 + * Since many are variable length we have to be careful about the memory
 10.1257 + * management.  We decree that all pointers to data in the object are
 10.1258 + * owned by the object and memory-managed by the object.
 10.1259 + *
 10.1260 + * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
 10.1261 + * functions to create all instances.  When using the
 10.1262 + * FLAC__metadata_object_set_*() functions to set pointers to data, set
 10.1263 + * \a copy to \c true to have the function make it's own copy of the data, or
 10.1264 + * to \c false to give the object ownership of your data.  In the latter case
 10.1265 + * your pointer must be freeable by free() and will be free()d when the object
 10.1266 + * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
 10.1267 + * the data pointer to a FLAC__metadata_object_set_*() function as long as
 10.1268 + * the length argument is 0 and the \a copy argument is \c false.
 10.1269 + *
 10.1270 + * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
 10.1271 + * will return \c NULL in the case of a memory allocation error, otherwise a new
 10.1272 + * object.  The FLAC__metadata_object_set_*() functions return \c false in the
 10.1273 + * case of a memory allocation error.
 10.1274 + *
 10.1275 + * We don't have the convenience of C++ here, so note that the library relies
 10.1276 + * on you to keep the types straight.  In other words, if you pass, for
 10.1277 + * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
 10.1278 + * FLAC__metadata_object_application_set_data(), you will get an assertion
 10.1279 + * failure.
 10.1280 + *
 10.1281 + * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
 10.1282 + * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
 10.1283 + * toward the length or stored in the stream, but it can make working with plain
 10.1284 + * comments (those that don't contain embedded-NULs in the value) easier.
 10.1285 + * Entries passed into these functions have trailing NULs added if missing, and
 10.1286 + * returned entries are guaranteed to have a trailing NUL.
 10.1287 + *
 10.1288 + * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
 10.1289 + * comment entry/name/value will first validate that it complies with the Vorbis
 10.1290 + * comment specification and return false if it does not.
 10.1291 + *
 10.1292 + * There is no need to recalculate the length field on metadata blocks you
 10.1293 + * have modified.  They will be calculated automatically before they  are
 10.1294 + * written back to a file.
 10.1295 + *
 10.1296 + * \{
 10.1297 + */
 10.1298 +
 10.1299 +
 10.1300 +/** Create a new metadata object instance of the given type.
 10.1301 + *
 10.1302 + *  The object will be "empty"; i.e. values and data pointers will be \c 0,
 10.1303 + *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
 10.1304 + *  the vendor string set (but zero comments).
 10.1305 + *
 10.1306 + *  Do not pass in a value greater than or equal to
 10.1307 + *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
 10.1308 + *  doing.
 10.1309 + *
 10.1310 + * \param type  Type of object to create
 10.1311 + * \retval FLAC__StreamMetadata*
 10.1312 + *    \c NULL if there was an error allocating memory or the type code is
 10.1313 + *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
 10.1314 + */
 10.1315 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
 10.1316 +
 10.1317 +/** Create a copy of an existing metadata object.
 10.1318 + *
 10.1319 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
 10.1320 + *  object is also copied.  The caller takes ownership of the new block and
 10.1321 + *  is responsible for freeing it with FLAC__metadata_object_delete().
 10.1322 + *
 10.1323 + * \param object  Pointer to object to copy.
 10.1324 + * \assert
 10.1325 + *    \code object != NULL \endcode
 10.1326 + * \retval FLAC__StreamMetadata*
 10.1327 + *    \c NULL if there was an error allocating memory, else the new instance.
 10.1328 + */
 10.1329 +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
 10.1330 +
 10.1331 +/** Free a metadata object.  Deletes the object pointed to by \a object.
 10.1332 + *
 10.1333 + *  The delete is a "deep" delete, i.e. dynamically allocated data within the
 10.1334 + *  object is also deleted.
 10.1335 + *
 10.1336 + * \param object  A pointer to an existing object.
 10.1337 + * \assert
 10.1338 + *    \code object != NULL \endcode
 10.1339 + */
 10.1340 +FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
 10.1341 +
 10.1342 +/** Compares two metadata objects.
 10.1343 + *
 10.1344 + *  The compare is "deep", i.e. dynamically allocated data within the
 10.1345 + *  object is also compared.
 10.1346 + *
 10.1347 + * \param block1  A pointer to an existing object.
 10.1348 + * \param block2  A pointer to an existing object.
 10.1349 + * \assert
 10.1350 + *    \code block1 != NULL \endcode
 10.1351 + *    \code block2 != NULL \endcode
 10.1352 + * \retval FLAC__bool
 10.1353 + *    \c true if objects are identical, else \c false.
 10.1354 + */
 10.1355 +FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
 10.1356 +
 10.1357 +/** Sets the application data of an APPLICATION block.
 10.1358 + *
 10.1359 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
 10.1360 + *  takes ownership of the pointer.  The existing data will be freed if this
 10.1361 + *  function is successful, otherwise the original data will remain if \a copy
 10.1362 + *  is \c true and malloc() fails.
 10.1363 + *
 10.1364 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
 10.1365 + *
 10.1366 + * \param object  A pointer to an existing APPLICATION object.
 10.1367 + * \param data    A pointer to the data to set.
 10.1368 + * \param length  The length of \a data in bytes.
 10.1369 + * \param copy    See above.
 10.1370 + * \assert
 10.1371 + *    \code object != NULL \endcode
 10.1372 + *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
 10.1373 + *    \code (data != NULL && length > 0) ||
 10.1374 + * (data == NULL && length == 0 && copy == false) \endcode
 10.1375 + * \retval FLAC__bool
 10.1376 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.1377 + */
 10.1378 +FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
 10.1379 +
 10.1380 +/** Resize the seekpoint array.
 10.1381 + *
 10.1382 + *  If the size shrinks, elements will truncated; if it grows, new placeholder
 10.1383 + *  points will be added to the end.
 10.1384 + *
 10.1385 + * \param object          A pointer to an existing SEEKTABLE object.
 10.1386 + * \param new_num_points  The desired length of the array; may be \c 0.
 10.1387 + * \assert
 10.1388 + *    \code object != NULL \endcode
 10.1389 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1390 + *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
 10.1391 + * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
 10.1392 + * \retval FLAC__bool
 10.1393 + *    \c false if memory allocation error, else \c true.
 10.1394 + */
 10.1395 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
 10.1396 +
 10.1397 +/** Set a seekpoint in a seektable.
 10.1398 + *
 10.1399 + * \param object     A pointer to an existing SEEKTABLE object.
 10.1400 + * \param point_num  Index into seekpoint array to set.
 10.1401 + * \param point      The point to set.
 10.1402 + * \assert
 10.1403 + *    \code object != NULL \endcode
 10.1404 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1405 + *    \code object->data.seek_table.num_points > point_num \endcode
 10.1406 + */
 10.1407 +FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
 10.1408 +
 10.1409 +/** Insert a seekpoint into a seektable.
 10.1410 + *
 10.1411 + * \param object     A pointer to an existing SEEKTABLE object.
 10.1412 + * \param point_num  Index into seekpoint array to set.
 10.1413 + * \param point      The point to set.
 10.1414 + * \assert
 10.1415 + *    \code object != NULL \endcode
 10.1416 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1417 + *    \code object->data.seek_table.num_points >= point_num \endcode
 10.1418 + * \retval FLAC__bool
 10.1419 + *    \c false if memory allocation error, else \c true.
 10.1420 + */
 10.1421 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
 10.1422 +
 10.1423 +/** Delete a seekpoint from a seektable.
 10.1424 + *
 10.1425 + * \param object     A pointer to an existing SEEKTABLE object.
 10.1426 + * \param point_num  Index into seekpoint array to set.
 10.1427 + * \assert
 10.1428 + *    \code object != NULL \endcode
 10.1429 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1430 + *    \code object->data.seek_table.num_points > point_num \endcode
 10.1431 + * \retval FLAC__bool
 10.1432 + *    \c false if memory allocation error, else \c true.
 10.1433 + */
 10.1434 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
 10.1435 +
 10.1436 +/** Check a seektable to see if it conforms to the FLAC specification.
 10.1437 + *  See the format specification for limits on the contents of the
 10.1438 + *  seektable.
 10.1439 + *
 10.1440 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1441 + * \assert
 10.1442 + *    \code object != NULL \endcode
 10.1443 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1444 + * \retval FLAC__bool
 10.1445 + *    \c false if seek table is illegal, else \c true.
 10.1446 + */
 10.1447 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
 10.1448 +
 10.1449 +/** Append a number of placeholder points to the end of a seek table.
 10.1450 + *
 10.1451 + * \note
 10.1452 + * As with the other ..._seektable_template_... functions, you should
 10.1453 + * call FLAC__metadata_object_seektable_template_sort() when finished
 10.1454 + * to make the seek table legal.
 10.1455 + *
 10.1456 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1457 + * \param num     The number of placeholder points to append.
 10.1458 + * \assert
 10.1459 + *    \code object != NULL \endcode
 10.1460 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1461 + * \retval FLAC__bool
 10.1462 + *    \c false if memory allocation fails, else \c true.
 10.1463 + */
 10.1464 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
 10.1465 +
 10.1466 +/** Append a specific seek point template to the end of a seek table.
 10.1467 + *
 10.1468 + * \note
 10.1469 + * As with the other ..._seektable_template_... functions, you should
 10.1470 + * call FLAC__metadata_object_seektable_template_sort() when finished
 10.1471 + * to make the seek table legal.
 10.1472 + *
 10.1473 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1474 + * \param sample_number  The sample number of the seek point template.
 10.1475 + * \assert
 10.1476 + *    \code object != NULL \endcode
 10.1477 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1478 + * \retval FLAC__bool
 10.1479 + *    \c false if memory allocation fails, else \c true.
 10.1480 + */
 10.1481 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
 10.1482 +
 10.1483 +/** Append specific seek point templates to the end of a seek table.
 10.1484 + *
 10.1485 + * \note
 10.1486 + * As with the other ..._seektable_template_... functions, you should
 10.1487 + * call FLAC__metadata_object_seektable_template_sort() when finished
 10.1488 + * to make the seek table legal.
 10.1489 + *
 10.1490 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1491 + * \param sample_numbers  An array of sample numbers for the seek points.
 10.1492 + * \param num     The number of seek point templates to append.
 10.1493 + * \assert
 10.1494 + *    \code object != NULL \endcode
 10.1495 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1496 + * \retval FLAC__bool
 10.1497 + *    \c false if memory allocation fails, else \c true.
 10.1498 + */
 10.1499 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
 10.1500 +
 10.1501 +/** Append a set of evenly-spaced seek point templates to the end of a
 10.1502 + *  seek table.
 10.1503 + *
 10.1504 + * \note
 10.1505 + * As with the other ..._seektable_template_... functions, you should
 10.1506 + * call FLAC__metadata_object_seektable_template_sort() when finished
 10.1507 + * to make the seek table legal.
 10.1508 + *
 10.1509 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1510 + * \param num     The number of placeholder points to append.
 10.1511 + * \param total_samples  The total number of samples to be encoded;
 10.1512 + *                       the seekpoints will be spaced approximately
 10.1513 + *                       \a total_samples / \a num samples apart.
 10.1514 + * \assert
 10.1515 + *    \code object != NULL \endcode
 10.1516 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1517 + *    \code total_samples > 0 \endcode
 10.1518 + * \retval FLAC__bool
 10.1519 + *    \c false if memory allocation fails, else \c true.
 10.1520 + */
 10.1521 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
 10.1522 +
 10.1523 +/** Append a set of evenly-spaced seek point templates to the end of a
 10.1524 + *  seek table.
 10.1525 + *
 10.1526 + * \note
 10.1527 + * As with the other ..._seektable_template_... functions, you should
 10.1528 + * call FLAC__metadata_object_seektable_template_sort() when finished
 10.1529 + * to make the seek table legal.
 10.1530 + *
 10.1531 + * \param object  A pointer to an existing SEEKTABLE object.
 10.1532 + * \param samples The number of samples apart to space the placeholder
 10.1533 + *                points.  The first point will be at sample \c 0, the
 10.1534 + *                second at sample \a samples, then 2*\a samples, and
 10.1535 + *                so on.  As long as \a samples and \a total_samples
 10.1536 + *                are greater than \c 0, there will always be at least
 10.1537 + *                one seekpoint at sample \c 0.
 10.1538 + * \param total_samples  The total number of samples to be encoded;
 10.1539 + *                       the seekpoints will be spaced
 10.1540 + *                       \a samples samples apart.
 10.1541 + * \assert
 10.1542 + *    \code object != NULL \endcode
 10.1543 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1544 + *    \code samples > 0 \endcode
 10.1545 + *    \code total_samples > 0 \endcode
 10.1546 + * \retval FLAC__bool
 10.1547 + *    \c false if memory allocation fails, else \c true.
 10.1548 + */
 10.1549 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
 10.1550 +
 10.1551 +/** Sort a seek table's seek points according to the format specification,
 10.1552 + *  removing duplicates.
 10.1553 + *
 10.1554 + * \param object   A pointer to a seek table to be sorted.
 10.1555 + * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
 10.1556 + *                 If \c true, duplicates are deleted and the seek table is
 10.1557 + *                 shrunk appropriately; the number of placeholder points
 10.1558 + *                 present in the seek table will be the same after the call
 10.1559 + *                 as before.
 10.1560 + * \assert
 10.1561 + *    \code object != NULL \endcode
 10.1562 + *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 10.1563 + * \retval FLAC__bool
 10.1564 + *    \c false if realloc() fails, else \c true.
 10.1565 + */
 10.1566 +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
 10.1567 +
 10.1568 +/** Sets the vendor string in a VORBIS_COMMENT block.
 10.1569 + *
 10.1570 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 10.1571 + *  one already.
 10.1572 + *
 10.1573 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 10.1574 + *  takes ownership of the \c entry.entry pointer.
 10.1575 + *
 10.1576 + *  \note If this function returns \c false, the caller still owns the
 10.1577 + *  pointer.
 10.1578 + *
 10.1579 + * \param object  A pointer to an existing VORBIS_COMMENT object.
 10.1580 + * \param entry   The entry to set the vendor string to.
 10.1581 + * \param copy    See above.
 10.1582 + * \assert
 10.1583 + *    \code object != NULL \endcode
 10.1584 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1585 + *    \code (entry.entry != NULL && entry.length > 0) ||
 10.1586 + * (entry.entry == NULL && entry.length == 0) \endcode
 10.1587 + * \retval FLAC__bool
 10.1588 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1589 + *    Vorbis comment specification, else \c true.
 10.1590 + */
 10.1591 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 10.1592 +
 10.1593 +/** Resize the comment array.
 10.1594 + *
 10.1595 + *  If the size shrinks, elements will truncated; if it grows, new empty
 10.1596 + *  fields will be added to the end.
 10.1597 + *
 10.1598 + * \param object            A pointer to an existing VORBIS_COMMENT object.
 10.1599 + * \param new_num_comments  The desired length of the array; may be \c 0.
 10.1600 + * \assert
 10.1601 + *    \code object != NULL \endcode
 10.1602 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1603 + *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
 10.1604 + * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
 10.1605 + * \retval FLAC__bool
 10.1606 + *    \c false if memory allocation fails, else \c true.
 10.1607 + */
 10.1608 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
 10.1609 +
 10.1610 +/** Sets a comment in a VORBIS_COMMENT block.
 10.1611 + *
 10.1612 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 10.1613 + *  one already.
 10.1614 + *
 10.1615 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 10.1616 + *  takes ownership of the \c entry.entry pointer.
 10.1617 + *
 10.1618 + *  \note If this function returns \c false, the caller still owns the
 10.1619 + *  pointer.
 10.1620 + *
 10.1621 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 10.1622 + * \param comment_num  Index into comment array to set.
 10.1623 + * \param entry        The entry to set the comment to.
 10.1624 + * \param copy         See above.
 10.1625 + * \assert
 10.1626 + *    \code object != NULL \endcode
 10.1627 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1628 + *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
 10.1629 + *    \code (entry.entry != NULL && entry.length > 0) ||
 10.1630 + * (entry.entry == NULL && entry.length == 0) \endcode
 10.1631 + * \retval FLAC__bool
 10.1632 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1633 + *    Vorbis comment specification, else \c true.
 10.1634 + */
 10.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);
 10.1636 +
 10.1637 +/** Insert a comment in a VORBIS_COMMENT block at the given index.
 10.1638 + *
 10.1639 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 10.1640 + *  one already.
 10.1641 + *
 10.1642 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 10.1643 + *  takes ownership of the \c entry.entry pointer.
 10.1644 + *
 10.1645 + *  \note If this function returns \c false, the caller still owns the
 10.1646 + *  pointer.
 10.1647 + *
 10.1648 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 10.1649 + * \param comment_num  The index at which to insert the comment.  The comments
 10.1650 + *                     at and after \a comment_num move right one position.
 10.1651 + *                     To append a comment to the end, set \a comment_num to
 10.1652 + *                     \c object->data.vorbis_comment.num_comments .
 10.1653 + * \param entry        The comment to insert.
 10.1654 + * \param copy         See above.
 10.1655 + * \assert
 10.1656 + *    \code object != NULL \endcode
 10.1657 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1658 + *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
 10.1659 + *    \code (entry.entry != NULL && entry.length > 0) ||
 10.1660 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 10.1661 + * \retval FLAC__bool
 10.1662 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1663 + *    Vorbis comment specification, else \c true.
 10.1664 + */
 10.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);
 10.1666 +
 10.1667 +/** Appends a comment to a VORBIS_COMMENT block.
 10.1668 + *
 10.1669 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 10.1670 + *  one already.
 10.1671 + *
 10.1672 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 10.1673 + *  takes ownership of the \c entry.entry pointer.
 10.1674 + *
 10.1675 + *  \note If this function returns \c false, the caller still owns the
 10.1676 + *  pointer.
 10.1677 + *
 10.1678 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 10.1679 + * \param entry        The comment to insert.
 10.1680 + * \param copy         See above.
 10.1681 + * \assert
 10.1682 + *    \code object != NULL \endcode
 10.1683 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1684 + *    \code (entry.entry != NULL && entry.length > 0) ||
 10.1685 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 10.1686 + * \retval FLAC__bool
 10.1687 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1688 + *    Vorbis comment specification, else \c true.
 10.1689 + */
 10.1690 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
 10.1691 +
 10.1692 +/** Replaces comments in a VORBIS_COMMENT block with a new one.
 10.1693 + *
 10.1694 + *  For convenience, a trailing NUL is added to the entry if it doesn't have
 10.1695 + *  one already.
 10.1696 + *
 10.1697 + *  Depending on the the value of \a all, either all or just the first comment
 10.1698 + *  whose field name(s) match the given entry's name will be replaced by the
 10.1699 + *  given entry.  If no comments match, \a entry will simply be appended.
 10.1700 + *
 10.1701 + *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
 10.1702 + *  takes ownership of the \c entry.entry pointer.
 10.1703 + *
 10.1704 + *  \note If this function returns \c false, the caller still owns the
 10.1705 + *  pointer.
 10.1706 + *
 10.1707 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 10.1708 + * \param entry        The comment to insert.
 10.1709 + * \param all          If \c true, all comments whose field name matches
 10.1710 + *                     \a entry's field name will be removed, and \a entry will
 10.1711 + *                     be inserted at the position of the first matching
 10.1712 + *                     comment.  If \c false, only the first comment whose
 10.1713 + *                     field name matches \a entry's field name will be
 10.1714 + *                     replaced with \a entry.
 10.1715 + * \param copy         See above.
 10.1716 + * \assert
 10.1717 + *    \code object != NULL \endcode
 10.1718 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1719 + *    \code (entry.entry != NULL && entry.length > 0) ||
 10.1720 + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
 10.1721 + * \retval FLAC__bool
 10.1722 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1723 + *    Vorbis comment specification, else \c true.
 10.1724 + */
 10.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);
 10.1726 +
 10.1727 +/** Delete a comment in a VORBIS_COMMENT block at the given index.
 10.1728 + *
 10.1729 + * \param object       A pointer to an existing VORBIS_COMMENT object.
 10.1730 + * \param comment_num  The index of the comment to delete.
 10.1731 + * \assert
 10.1732 + *    \code object != NULL \endcode
 10.1733 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1734 + *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
 10.1735 + * \retval FLAC__bool
 10.1736 + *    \c false if realloc() fails, else \c true.
 10.1737 + */
 10.1738 +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
 10.1739 +
 10.1740 +/** Creates a Vorbis comment entry from NUL-terminated name and value strings.
 10.1741 + *
 10.1742 + *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
 10.1743 + *  memory and shall be owned by the caller.  For convenience the entry will
 10.1744 + *  have a terminating NUL.
 10.1745 + *
 10.1746 + * \param entry              A pointer to a Vorbis comment entry.  The entry's
 10.1747 + *                           \c entry pointer should not point to allocated
 10.1748 + *                           memory as it will be overwritten.
 10.1749 + * \param field_name         The field name in ASCII, \c NUL terminated.
 10.1750 + * \param field_value        The field value in UTF-8, \c NUL terminated.
 10.1751 + * \assert
 10.1752 + *    \code entry != NULL \endcode
 10.1753 + *    \code field_name != NULL \endcode
 10.1754 + *    \code field_value != NULL \endcode
 10.1755 + * \retval FLAC__bool
 10.1756 + *    \c false if malloc() fails, or if \a field_name or \a field_value does
 10.1757 + *    not comply with the Vorbis comment specification, else \c true.
 10.1758 + */
 10.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);
 10.1760 +
 10.1761 +/** Splits a Vorbis comment entry into NUL-terminated name and value strings.
 10.1762 + *
 10.1763 + *  The returned pointers to name and value will be allocated by malloc()
 10.1764 + *  and shall be owned by the caller.
 10.1765 + *
 10.1766 + * \param entry              An existing Vorbis comment entry.
 10.1767 + * \param field_name         The address of where the returned pointer to the
 10.1768 + *                           field name will be stored.
 10.1769 + * \param field_value        The address of where the returned pointer to the
 10.1770 + *                           field value will be stored.
 10.1771 + * \assert
 10.1772 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
 10.1773 + *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
 10.1774 + *    \code field_name != NULL \endcode
 10.1775 + *    \code field_value != NULL \endcode
 10.1776 + * \retval FLAC__bool
 10.1777 + *    \c false if memory allocation fails or \a entry does not comply with the
 10.1778 + *    Vorbis comment specification, else \c true.
 10.1779 + */
 10.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);
 10.1781 +
 10.1782 +/** Check if the given Vorbis comment entry's field name matches the given
 10.1783 + *  field name.
 10.1784 + *
 10.1785 + * \param entry              An existing Vorbis comment entry.
 10.1786 + * \param field_name         The field name to check.
 10.1787 + * \param field_name_length  The length of \a field_name, not including the
 10.1788 + *                           terminating \c NUL.
 10.1789 + * \assert
 10.1790 + *    \code (entry.entry != NULL && entry.length > 0) \endcode
 10.1791 + * \retval FLAC__bool
 10.1792 + *    \c true if the field names match, else \c false
 10.1793 + */
 10.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);
 10.1795 +
 10.1796 +/** Find a Vorbis comment with the given field name.
 10.1797 + *
 10.1798 + *  The search begins at entry number \a offset; use an offset of 0 to
 10.1799 + *  search from the beginning of the comment array.
 10.1800 + *
 10.1801 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 10.1802 + * \param offset      The offset into the comment array from where to start
 10.1803 + *                    the search.
 10.1804 + * \param field_name  The field name of the comment to find.
 10.1805 + * \assert
 10.1806 + *    \code object != NULL \endcode
 10.1807 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1808 + *    \code field_name != NULL \endcode
 10.1809 + * \retval int
 10.1810 + *    The offset in the comment array of the first comment whose field
 10.1811 + *    name matches \a field_name, or \c -1 if no match was found.
 10.1812 + */
 10.1813 +FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
 10.1814 +
 10.1815 +/** Remove first Vorbis comment matching the given field name.
 10.1816 + *
 10.1817 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 10.1818 + * \param field_name  The field name of comment to delete.
 10.1819 + * \assert
 10.1820 + *    \code object != NULL \endcode
 10.1821 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1822 + * \retval int
 10.1823 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
 10.1824 + *    \c 1 for one matching entry deleted.
 10.1825 + */
 10.1826 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
 10.1827 +
 10.1828 +/** Remove all Vorbis comments matching the given field name.
 10.1829 + *
 10.1830 + * \param object      A pointer to an existing VORBIS_COMMENT object.
 10.1831 + * \param field_name  The field name of comments to delete.
 10.1832 + * \assert
 10.1833 + *    \code object != NULL \endcode
 10.1834 + *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
 10.1835 + * \retval int
 10.1836 + *    \c -1 for memory allocation error, \c 0 for no matching entries,
 10.1837 + *    else the number of matching entries deleted.
 10.1838 + */
 10.1839 +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
 10.1840 +
 10.1841 +/** Create a new CUESHEET track instance.
 10.1842 + *
 10.1843 + *  The object will be "empty"; i.e. values and data pointers will be \c 0.
 10.1844 + *
 10.1845 + * \retval FLAC__StreamMetadata_CueSheet_Track*
 10.1846 + *    \c NULL if there was an error allocating memory, else the new instance.
 10.1847 + */
 10.1848 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
 10.1849 +
 10.1850 +/** Create a copy of an existing CUESHEET track object.
 10.1851 + *
 10.1852 + *  The copy is a "deep" copy, i.e. dynamically allocated data within the
 10.1853 + *  object is also copied.  The caller takes ownership of the new object and
 10.1854 + *  is responsible for freeing it with
 10.1855 + *  FLAC__metadata_object_cuesheet_track_delete().
 10.1856 + *
 10.1857 + * \param object  Pointer to object to copy.
 10.1858 + * \assert
 10.1859 + *    \code object != NULL \endcode
 10.1860 + * \retval FLAC__StreamMetadata_CueSheet_Track*
 10.1861 + *    \c NULL if there was an error allocating memory, else the new instance.
 10.1862 + */
 10.1863 +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
 10.1864 +
 10.1865 +/** Delete a CUESHEET track object
 10.1866 + *
 10.1867 + * \param object       A pointer to an existing CUESHEET track object.
 10.1868 + * \assert
 10.1869 + *    \code object != NULL \endcode
 10.1870 + */
 10.1871 +FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
 10.1872 +
 10.1873 +/** Resize a track's index point array.
 10.1874 + *
 10.1875 + *  If the size shrinks, elements will truncated; if it grows, new blank
 10.1876 + *  indices will be added to the end.
 10.1877 + *
 10.1878 + * \param object           A pointer to an existing CUESHEET object.
 10.1879 + * \param track_num        The index of the track to modify.  NOTE: this is not
 10.1880 + *                         necessarily the same as the track's \a number field.
 10.1881 + * \param new_num_indices  The desired length of the array; may be \c 0.
 10.1882 + * \assert
 10.1883 + *    \code object != NULL \endcode
 10.1884 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1885 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 10.1886 + *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
 10.1887 + * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
 10.1888 + * \retval FLAC__bool
 10.1889 + *    \c false if memory allocation error, else \c true.
 10.1890 + */
 10.1891 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
 10.1892 +
 10.1893 +/** Insert an index point in a CUESHEET track at the given index.
 10.1894 + *
 10.1895 + * \param object       A pointer to an existing CUESHEET object.
 10.1896 + * \param track_num    The index of the track to modify.  NOTE: this is not
 10.1897 + *                     necessarily the same as the track's \a number field.
 10.1898 + * \param index_num    The index into the track's index array at which to
 10.1899 + *                     insert the index point.  NOTE: this is not necessarily
 10.1900 + *                     the same as the index point's \a number field.  The
 10.1901 + *                     indices at and after \a index_num move right one
 10.1902 + *                     position.  To append an index point to the end, set
 10.1903 + *                     \a index_num to
 10.1904 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
 10.1905 + * \param index        The index point to insert.
 10.1906 + * \assert
 10.1907 + *    \code object != NULL \endcode
 10.1908 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1909 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 10.1910 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
 10.1911 + * \retval FLAC__bool
 10.1912 + *    \c false if realloc() fails, else \c true.
 10.1913 + */
 10.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);
 10.1915 +
 10.1916 +/** Insert a blank index point in a CUESHEET track at the given index.
 10.1917 + *
 10.1918 + *  A blank index point is one in which all field values are zero.
 10.1919 + *
 10.1920 + * \param object       A pointer to an existing CUESHEET object.
 10.1921 + * \param track_num    The index of the track to modify.  NOTE: this is not
 10.1922 + *                     necessarily the same as the track's \a number field.
 10.1923 + * \param index_num    The index into the track's index array at which to
 10.1924 + *                     insert the index point.  NOTE: this is not necessarily
 10.1925 + *                     the same as the index point's \a number field.  The
 10.1926 + *                     indices at and after \a index_num move right one
 10.1927 + *                     position.  To append an index point to the end, set
 10.1928 + *                     \a index_num to
 10.1929 + *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
 10.1930 + * \assert
 10.1931 + *    \code object != NULL \endcode
 10.1932 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1933 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 10.1934 + *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
 10.1935 + * \retval FLAC__bool
 10.1936 + *    \c false if realloc() fails, else \c true.
 10.1937 + */
 10.1938 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
 10.1939 +
 10.1940 +/** Delete an index point in a CUESHEET track at the given index.
 10.1941 + *
 10.1942 + * \param object       A pointer to an existing CUESHEET object.
 10.1943 + * \param track_num    The index into the track array of the track to
 10.1944 + *                     modify.  NOTE: this is not necessarily the same
 10.1945 + *                     as the track's \a number field.
 10.1946 + * \param index_num    The index into the track's index array of the index
 10.1947 + *                     to delete.  NOTE: this is not necessarily the same
 10.1948 + *                     as the index's \a number field.
 10.1949 + * \assert
 10.1950 + *    \code object != NULL \endcode
 10.1951 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1952 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 10.1953 + *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
 10.1954 + * \retval FLAC__bool
 10.1955 + *    \c false if realloc() fails, else \c true.
 10.1956 + */
 10.1957 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
 10.1958 +
 10.1959 +/** Resize the track array.
 10.1960 + *
 10.1961 + *  If the size shrinks, elements will truncated; if it grows, new blank
 10.1962 + *  tracks will be added to the end.
 10.1963 + *
 10.1964 + * \param object            A pointer to an existing CUESHEET object.
 10.1965 + * \param new_num_tracks    The desired length of the array; may be \c 0.
 10.1966 + * \assert
 10.1967 + *    \code object != NULL \endcode
 10.1968 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1969 + *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
 10.1970 + * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
 10.1971 + * \retval FLAC__bool
 10.1972 + *    \c false if memory allocation error, else \c true.
 10.1973 + */
 10.1974 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
 10.1975 +
 10.1976 +/** Sets a track in a CUESHEET block.
 10.1977 + *
 10.1978 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
 10.1979 + *  takes ownership of the \a track pointer.
 10.1980 + *
 10.1981 + * \param object       A pointer to an existing CUESHEET object.
 10.1982 + * \param track_num    Index into track array to set.  NOTE: this is not
 10.1983 + *                     necessarily the same as the track's \a number field.
 10.1984 + * \param track        The track to set the track to.  You may safely pass in
 10.1985 + *                     a const pointer if \a copy is \c true.
 10.1986 + * \param copy         See above.
 10.1987 + * \assert
 10.1988 + *    \code object != NULL \endcode
 10.1989 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.1990 + *    \code track_num < object->data.cue_sheet.num_tracks \endcode
 10.1991 + *    \code (track->indices != NULL && track->num_indices > 0) ||
 10.1992 + * (track->indices == NULL && track->num_indices == 0)
 10.1993 + * \retval FLAC__bool
 10.1994 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.1995 + */
 10.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);
 10.1997 +
 10.1998 +/** Insert a track in a CUESHEET block at the given index.
 10.1999 + *
 10.2000 + *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
 10.2001 + *  takes ownership of the \a track pointer.
 10.2002 + *
 10.2003 + * \param object       A pointer to an existing CUESHEET object.
 10.2004 + * \param track_num    The index at which to insert the track.  NOTE: this
 10.2005 + *                     is not necessarily the same as the track's \a number
 10.2006 + *                     field.  The tracks at and after \a track_num move right
 10.2007 + *                     one position.  To append a track to the end, set
 10.2008 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
 10.2009 + * \param track        The track to insert.  You may safely pass in a const
 10.2010 + *                     pointer if \a copy is \c true.
 10.2011 + * \param copy         See above.
 10.2012 + * \assert
 10.2013 + *    \code object != NULL \endcode
 10.2014 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.2015 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
 10.2016 + * \retval FLAC__bool
 10.2017 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.2018 + */
 10.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);
 10.2020 +
 10.2021 +/** Insert a blank track in a CUESHEET block at the given index.
 10.2022 + *
 10.2023 + *  A blank track is one in which all field values are zero.
 10.2024 + *
 10.2025 + * \param object       A pointer to an existing CUESHEET object.
 10.2026 + * \param track_num    The index at which to insert the track.  NOTE: this
 10.2027 + *                     is not necessarily the same as the track's \a number
 10.2028 + *                     field.  The tracks at and after \a track_num move right
 10.2029 + *                     one position.  To append a track to the end, set
 10.2030 + *                     \a track_num to \c object->data.cue_sheet.num_tracks .
 10.2031 + * \assert
 10.2032 + *    \code object != NULL \endcode
 10.2033 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.2034 + *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
 10.2035 + * \retval FLAC__bool
 10.2036 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.2037 + */
 10.2038 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
 10.2039 +
 10.2040 +/** Delete a track in a CUESHEET block at the given index.
 10.2041 + *
 10.2042 + * \param object       A pointer to an existing CUESHEET object.
 10.2043 + * \param track_num    The index into the track array of the track to
 10.2044 + *                     delete.  NOTE: this is not necessarily the same
 10.2045 + *                     as the track's \a number field.
 10.2046 + * \assert
 10.2047 + *    \code object != NULL \endcode
 10.2048 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.2049 + *    \code object->data.cue_sheet.num_tracks > track_num \endcode
 10.2050 + * \retval FLAC__bool
 10.2051 + *    \c false if realloc() fails, else \c true.
 10.2052 + */
 10.2053 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
 10.2054 +
 10.2055 +/** Check a cue sheet to see if it conforms to the FLAC specification.
 10.2056 + *  See the format specification for limits on the contents of the
 10.2057 + *  cue sheet.
 10.2058 + *
 10.2059 + * \param object     A pointer to an existing CUESHEET object.
 10.2060 + * \param check_cd_da_subset  If \c true, check CUESHEET against more
 10.2061 + *                   stringent requirements for a CD-DA (audio) disc.
 10.2062 + * \param violation  Address of a pointer to a string.  If there is a
 10.2063 + *                   violation, a pointer to a string explanation of the
 10.2064 + *                   violation will be returned here. \a violation may be
 10.2065 + *                   \c NULL if you don't need the returned string.  Do not
 10.2066 + *                   free the returned string; it will always point to static
 10.2067 + *                   data.
 10.2068 + * \assert
 10.2069 + *    \code object != NULL \endcode
 10.2070 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.2071 + * \retval FLAC__bool
 10.2072 + *    \c false if cue sheet is illegal, else \c true.
 10.2073 + */
 10.2074 +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
 10.2075 +
 10.2076 +/** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
 10.2077 + *  assumes the cue sheet corresponds to a CD; the result is undefined
 10.2078 + *  if the cuesheet's is_cd bit is not set.
 10.2079 + *
 10.2080 + * \param object     A pointer to an existing CUESHEET object.
 10.2081 + * \assert
 10.2082 + *    \code object != NULL \endcode
 10.2083 + *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 10.2084 + * \retval FLAC__uint32
 10.2085 + *    The unsigned integer representation of the CDDB/freedb ID
 10.2086 + */
 10.2087 +FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
 10.2088 +
 10.2089 +/** Sets the MIME type of a PICTURE block.
 10.2090 + *
 10.2091 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 10.2092 + *  takes ownership of the pointer.  The existing string will be freed if this
 10.2093 + *  function is successful, otherwise the original string will remain if \a copy
 10.2094 + *  is \c true and malloc() fails.
 10.2095 + *
 10.2096 + * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
 10.2097 + *
 10.2098 + * \param object      A pointer to an existing PICTURE object.
 10.2099 + * \param mime_type   A pointer to the MIME type string.  The string must be
 10.2100 + *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
 10.2101 + *                    is done.
 10.2102 + * \param copy        See above.
 10.2103 + * \assert
 10.2104 + *    \code object != NULL \endcode
 10.2105 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 10.2106 + *    \code (mime_type != NULL) \endcode
 10.2107 + * \retval FLAC__bool
 10.2108 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.2109 + */
 10.2110 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
 10.2111 +
 10.2112 +/** Sets the description of a PICTURE block.
 10.2113 + *
 10.2114 + *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 10.2115 + *  takes ownership of the pointer.  The existing string will be freed if this
 10.2116 + *  function is successful, otherwise the original string will remain if \a copy
 10.2117 + *  is \c true and malloc() fails.
 10.2118 + *
 10.2119 + * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
 10.2120 + *
 10.2121 + * \param object      A pointer to an existing PICTURE object.
 10.2122 + * \param description A pointer to the description string.  The string must be
 10.2123 + *                    valid UTF-8, NUL-terminated.  No validation is done.
 10.2124 + * \param copy        See above.
 10.2125 + * \assert
 10.2126 + *    \code object != NULL \endcode
 10.2127 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 10.2128 + *    \code (description != NULL) \endcode
 10.2129 + * \retval FLAC__bool
 10.2130 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.2131 + */
 10.2132 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
 10.2133 +
 10.2134 +/** Sets the picture data of a PICTURE block.
 10.2135 + *
 10.2136 + *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
 10.2137 + *  takes ownership of the pointer.  Also sets the \a data_length field of the
 10.2138 + *  metadata object to what is passed in as the \a length parameter.  The
 10.2139 + *  existing data will be freed if this function is successful, otherwise the
 10.2140 + *  original data and data_length will remain if \a copy is \c true and
 10.2141 + *  malloc() fails.
 10.2142 + *
 10.2143 + * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
 10.2144 + *
 10.2145 + * \param object  A pointer to an existing PICTURE object.
 10.2146 + * \param data    A pointer to the data to set.
 10.2147 + * \param length  The length of \a data in bytes.
 10.2148 + * \param copy    See above.
 10.2149 + * \assert
 10.2150 + *    \code object != NULL \endcode
 10.2151 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 10.2152 + *    \code (data != NULL && length > 0) ||
 10.2153 + * (data == NULL && length == 0 && copy == false) \endcode
 10.2154 + * \retval FLAC__bool
 10.2155 + *    \c false if \a copy is \c true and malloc() fails, else \c true.
 10.2156 + */
 10.2157 +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
 10.2158 +
 10.2159 +/** Check a PICTURE block to see if it conforms to the FLAC specification.
 10.2160 + *  See the format specification for limits on the contents of the
 10.2161 + *  PICTURE block.
 10.2162 + *
 10.2163 + * \param object     A pointer to existing PICTURE block to be checked.
 10.2164 + * \param violation  Address of a pointer to a string.  If there is a
 10.2165 + *                   violation, a pointer to a string explanation of the
 10.2166 + *                   violation will be returned here. \a violation may be
 10.2167 + *                   \c NULL if you don't need the returned string.  Do not
 10.2168 + *                   free the returned string; it will always point to static
 10.2169 + *                   data.
 10.2170 + * \assert
 10.2171 + *    \code object != NULL \endcode
 10.2172 + *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 10.2173 + * \retval FLAC__bool
 10.2174 + *    \c false if PICTURE block is illegal, else \c true.
 10.2175 + */
 10.2176 +FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
 10.2177 +
 10.2178 +/* \} */
 10.2179 +
 10.2180 +#ifdef __cplusplus
 10.2181 +}
 10.2182 +#endif
 10.2183 +
 10.2184 +#endif
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/VisualC/flac/include/FLAC/ordinals.h	Sun Jan 01 14:40:22 2012 -0500
    11.3 @@ -0,0 +1,80 @@
    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__ORDINALS_H
   11.36 +#define FLAC__ORDINALS_H
   11.37 +
   11.38 +#if !(defined(_MSC_VER) || defined(__BORLANDC__) || defined(__EMX__))
   11.39 +#include <inttypes.h>
   11.40 +#endif
   11.41 +
   11.42 +typedef signed char FLAC__int8;
   11.43 +typedef unsigned char FLAC__uint8;
   11.44 +
   11.45 +#if defined(_MSC_VER) || defined(__BORLANDC__)
   11.46 +typedef __int16 FLAC__int16;
   11.47 +typedef __int32 FLAC__int32;
   11.48 +typedef __int64 FLAC__int64;
   11.49 +typedef unsigned __int16 FLAC__uint16;
   11.50 +typedef unsigned __int32 FLAC__uint32;
   11.51 +typedef unsigned __int64 FLAC__uint64;
   11.52 +#elif defined(__EMX__)
   11.53 +typedef short FLAC__int16;
   11.54 +typedef long FLAC__int32;
   11.55 +typedef long long FLAC__int64;
   11.56 +typedef unsigned short FLAC__uint16;
   11.57 +typedef unsigned long FLAC__uint32;
   11.58 +typedef unsigned long long FLAC__uint64;
   11.59 +#else
   11.60 +typedef int16_t FLAC__int16;
   11.61 +typedef int32_t FLAC__int32;
   11.62 +typedef int64_t FLAC__int64;
   11.63 +typedef uint16_t FLAC__uint16;
   11.64 +typedef uint32_t FLAC__uint32;
   11.65 +typedef uint64_t FLAC__uint64;
   11.66 +#endif
   11.67 +
   11.68 +typedef int FLAC__bool;
   11.69 +
   11.70 +typedef FLAC__uint8 FLAC__byte;
   11.71 +
   11.72 +#ifdef true
   11.73 +#undef true
   11.74 +#endif
   11.75 +#ifdef false
   11.76 +#undef false
   11.77 +#endif
   11.78 +#ifndef __cplusplus
   11.79 +#define true 1
   11.80 +#define false 0
   11.81 +#endif
   11.82 +
   11.83 +#endif
    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/VisualC/flac/include/FLAC/stream_decoder.h	Sun Jan 01 14:40:22 2012 -0500
    12.3 @@ -0,0 +1,1559 @@
    12.4 +/* libFLAC - Free Lossless Audio Codec library
    12.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    12.6 + *
    12.7 + * Redistribution and use in source and binary forms, with or without
    12.8 + * modification, are permitted provided that the following conditions
    12.9 + * are met:
   12.10 + *
   12.11 + * - Redistributions of source code must retain the above copyright
   12.12 + * notice, this list of conditions and the following disclaimer.
   12.13 + *
   12.14 + * - Redistributions in binary form must reproduce the above copyright
   12.15 + * notice, this list of conditions and the following disclaimer in the
   12.16 + * documentation and/or other materials provided with the distribution.
   12.17 + *
   12.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   12.19 + * contributors may be used to endorse or promote products derived from
   12.20 + * this software without specific prior written permission.
   12.21 + *
   12.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   12.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   12.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   12.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   12.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   12.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   12.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   12.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   12.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   12.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   12.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   12.33 + */
   12.34 +
   12.35 +#ifndef FLAC__STREAM_DECODER_H
   12.36 +#define FLAC__STREAM_DECODER_H
   12.37 +
   12.38 +#include <stdio.h> /* for FILE */
   12.39 +#include "export.h"
   12.40 +#include "format.h"
   12.41 +
   12.42 +#ifdef __cplusplus
   12.43 +extern "C" {
   12.44 +#endif
   12.45 +
   12.46 +
   12.47 +/** \file include/FLAC/stream_decoder.h
   12.48 + *
   12.49 + *  \brief
   12.50 + *  This module contains the functions which implement the stream
   12.51 + *  decoder.
   12.52 + *
   12.53 + *  See the detailed documentation in the
   12.54 + *  \link flac_stream_decoder stream decoder \endlink module.
   12.55 + */
   12.56 +
   12.57 +/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
   12.58 + *  \ingroup flac
   12.59 + *
   12.60 + *  \brief
   12.61 + *  This module describes the decoder layers provided by libFLAC.
   12.62 + *
   12.63 + * The stream decoder can be used to decode complete streams either from
   12.64 + * the client via callbacks, or directly from a file, depending on how
   12.65 + * it is initialized.  When decoding via callbacks, the client provides
   12.66 + * callbacks for reading FLAC data and writing decoded samples, and
   12.67 + * handling metadata and errors.  If the client also supplies seek-related
   12.68 + * callback, the decoder function for sample-accurate seeking within the
   12.69 + * FLAC input is also available.  When decoding from a file, the client
   12.70 + * needs only supply a filename or open \c FILE* and write/metadata/error
   12.71 + * callbacks; the rest of the callbacks are supplied internally.  For more
   12.72 + * info see the \link flac_stream_decoder stream decoder \endlink module.
   12.73 + */
   12.74 +
   12.75 +/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
   12.76 + *  \ingroup flac_decoder
   12.77 + *
   12.78 + *  \brief
   12.79 + *  This module contains the functions which implement the stream
   12.80 + *  decoder.
   12.81 + *
   12.82 + * The stream decoder can decode native FLAC, and optionally Ogg FLAC
   12.83 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   12.84 + *
   12.85 + * The basic usage of this decoder is as follows:
   12.86 + * - The program creates an instance of a decoder using
   12.87 + *   FLAC__stream_decoder_new().
   12.88 + * - The program overrides the default settings using
   12.89 + *   FLAC__stream_decoder_set_*() functions.
   12.90 + * - The program initializes the instance to validate the settings and
   12.91 + *   prepare for decoding using
   12.92 + *   - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
   12.93 + *     or FLAC__stream_decoder_init_file() for native FLAC,
   12.94 + *   - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
   12.95 + *     or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
   12.96 + * - The program calls the FLAC__stream_decoder_process_*() functions
   12.97 + *   to decode data, which subsequently calls the callbacks.
   12.98 + * - The program finishes the decoding with FLAC__stream_decoder_finish(),
   12.99 + *   which flushes the input and output and resets the decoder to the
  12.100 + *   uninitialized state.
  12.101 + * - The instance may be used again or deleted with
  12.102 + *   FLAC__stream_decoder_delete().
  12.103 + *
  12.104 + * In more detail, the program will create a new instance by calling
  12.105 + * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
  12.106 + * functions to override the default decoder options, and call
  12.107 + * one of the FLAC__stream_decoder_init_*() functions.
  12.108 + *
  12.109 + * There are three initialization functions for native FLAC, one for
  12.110 + * setting up the decoder to decode FLAC data from the client via
  12.111 + * callbacks, and two for decoding directly from a FLAC file.
  12.112 + *
  12.113 + * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
  12.114 + * You must also supply several callbacks for handling I/O.  Some (like
  12.115 + * seeking) are optional, depending on the capabilities of the input.
  12.116 + *
  12.117 + * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
  12.118 + * or FLAC__stream_decoder_init_file().  Then you must only supply an open
  12.119 + * \c FILE* or filename and fewer callbacks; the decoder will handle
  12.120 + * the other callbacks internally.
  12.121 + *
  12.122 + * There are three similarly-named init functions for decoding from Ogg
  12.123 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  12.124 + * library has been built with Ogg support.
  12.125 + *
  12.126 + * Once the decoder is initialized, your program will call one of several
  12.127 + * functions to start the decoding process:
  12.128 + *
  12.129 + * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
  12.130 + *   most one metadata block or audio frame and return, calling either the
  12.131 + *   metadata callback or write callback, respectively, once.  If the decoder
  12.132 + *   loses sync it will return with only the error callback being called.
  12.133 + * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
  12.134 + *   to process the stream from the current location and stop upon reaching
  12.135 + *   the first audio frame.  The client will get one metadata, write, or error
  12.136 + *   callback per metadata block, audio frame, or sync error, respectively.
  12.137 + * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
  12.138 + *   to process the stream from the current location until the read callback
  12.139 + *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
  12.140 + *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The client will get one metadata,
  12.141 + *   write, or error callback per metadata block, audio frame, or sync error,
  12.142 + *   respectively.
  12.143 + *
  12.144 + * When the decoder has finished decoding (normally or through an abort),
  12.145 + * the instance is finished by calling FLAC__stream_decoder_finish(), which
  12.146 + * ensures the decoder is in the correct state and frees memory.  Then the
  12.147 + * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  12.148 + * again to decode another stream.
  12.149 + *
  12.150 + * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
  12.151 + * At any point after the stream decoder has been initialized, the client can
  12.152 + * call this function to seek to an exact sample within the stream.
  12.153 + * Subsequently, the first time the write callback is called it will be
  12.154 + * passed a (possibly partial) block starting at that sample.
  12.155 + *
  12.156 + * If the client cannot seek via the callback interface provided, but still
  12.157 + * has another way of seeking, it can flush the decoder using
  12.158 + * FLAC__stream_decoder_flush() and start feeding data from the new position
  12.159 + * through the read callback.
  12.160 + *
  12.161 + * The stream decoder also provides MD5 signature checking.  If this is
  12.162 + * turned on before initialization, FLAC__stream_decoder_finish() will
  12.163 + * report when the decoded MD5 signature does not match the one stored
  12.164 + * in the STREAMINFO block.  MD5 checking is automatically turned off
  12.165 + * (until the next FLAC__stream_decoder_reset()) if there is no signature
  12.166 + * in the STREAMINFO block or when a seek is attempted.
  12.167 + *
  12.168 + * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  12.169 + * attention.  By default, the decoder only calls the metadata_callback for
  12.170 + * the STREAMINFO block.  These functions allow you to tell the decoder
  12.171 + * explicitly which blocks to parse and return via the metadata_callback
  12.172 + * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
  12.173 + * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
  12.174 + * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
  12.175 + * which blocks to return.  Remember that metadata blocks can potentially
  12.176 + * be big (for example, cover art) so filtering out the ones you don't
  12.177 + * use can reduce the memory requirements of the decoder.  Also note the
  12.178 + * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
  12.179 + * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
  12.180 + * filtering APPLICATION blocks based on the application ID.
  12.181 + *
  12.182 + * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  12.183 + * they still can legally be filtered from the metadata_callback.
  12.184 + *
  12.185 + * \note
  12.186 + * The "set" functions may only be called when the decoder is in the
  12.187 + * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
  12.188 + * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
  12.189 + * before FLAC__stream_decoder_init_*().  If this is the case they will
  12.190 + * return \c true, otherwise \c false.
  12.191 + *
  12.192 + * \note
  12.193 + * FLAC__stream_decoder_finish() resets all settings to the constructor
  12.194 + * defaults, including the callbacks.
  12.195 + *
  12.196 + * \{
  12.197 + */
  12.198 +
  12.199 +
  12.200 +/** State values for a FLAC__StreamDecoder
  12.201 + *
  12.202 + * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  12.203 + */
  12.204 +typedef enum {
  12.205 +
  12.206 +	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
  12.207 +	/**< The decoder is ready to search for metadata. */
  12.208 +
  12.209 +	FLAC__STREAM_DECODER_READ_METADATA,
  12.210 +	/**< The decoder is ready to or is in the process of reading metadata. */
  12.211 +
  12.212 +	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
  12.213 +	/**< The decoder is ready to or is in the process of searching for the
  12.214 +	 * frame sync code.
  12.215 +	 */
  12.216 +
  12.217 +	FLAC__STREAM_DECODER_READ_FRAME,
  12.218 +	/**< The decoder is ready to or is in the process of reading a frame. */
  12.219 +
  12.220 +	FLAC__STREAM_DECODER_END_OF_STREAM,
  12.221 +	/**< The decoder has reached the end of the stream. */
  12.222 +
  12.223 +	FLAC__STREAM_DECODER_OGG_ERROR,
  12.224 +	/**< An error occurred in the underlying Ogg layer.  */
  12.225 +
  12.226 +	FLAC__STREAM_DECODER_SEEK_ERROR,
  12.227 +	/**< An error occurred while seeking.  The decoder must be flushed
  12.228 +	 * with FLAC__stream_decoder_flush() or reset with
  12.229 +	 * FLAC__stream_decoder_reset() before decoding can continue.
  12.230 +	 */
  12.231 +
  12.232 +	FLAC__STREAM_DECODER_ABORTED,
  12.233 +	/**< The decoder was aborted by the read callback. */
  12.234 +
  12.235 +	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  12.236 +	/**< An error occurred allocating memory.  The decoder is in an invalid
  12.237 +	 * state and can no longer be used.
  12.238 +	 */
  12.239 +
  12.240 +	FLAC__STREAM_DECODER_UNINITIALIZED
  12.241 +	/**< The decoder is in the uninitialized state; one of the
  12.242 +	 * FLAC__stream_decoder_init_*() functions must be called before samples
  12.243 +	 * can be processed.
  12.244 +	 */
  12.245 +
  12.246 +} FLAC__StreamDecoderState;
  12.247 +
  12.248 +/** Maps a FLAC__StreamDecoderState to a C string.
  12.249 + *
  12.250 + *  Using a FLAC__StreamDecoderState as the index to this array
  12.251 + *  will give the string equivalent.  The contents should not be modified.
  12.252 + */
  12.253 +extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
  12.254 +
  12.255 +
  12.256 +/** Possible return values for the FLAC__stream_decoder_init_*() functions.
  12.257 + */
  12.258 +typedef enum {
  12.259 +
  12.260 +	FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
  12.261 +	/**< Initialization was successful. */
  12.262 +
  12.263 +	FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  12.264 +	/**< The library was not compiled with support for the given container
  12.265 +	 * format.
  12.266 +	 */
  12.267 +
  12.268 +	FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
  12.269 +	/**< A required callback was not supplied. */
  12.270 +
  12.271 +	FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
  12.272 +	/**< An error occurred allocating memory. */
  12.273 +
  12.274 +	FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
  12.275 +	/**< fopen() failed in FLAC__stream_decoder_init_file() or
  12.276 +	 * FLAC__stream_decoder_init_ogg_file(). */
  12.277 +
  12.278 +	FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
  12.279 +	/**< FLAC__stream_decoder_init_*() was called when the decoder was
  12.280 +	 * already initialized, usually because
  12.281 +	 * FLAC__stream_decoder_finish() was not called.
  12.282 +	 */
  12.283 +
  12.284 +} FLAC__StreamDecoderInitStatus;
  12.285 +
  12.286 +/** Maps a FLAC__StreamDecoderInitStatus to a C string.
  12.287 + *
  12.288 + *  Using a FLAC__StreamDecoderInitStatus as the index to this array
  12.289 + *  will give the string equivalent.  The contents should not be modified.
  12.290 + */
  12.291 +extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
  12.292 +
  12.293 +
  12.294 +/** Return values for the FLAC__StreamDecoder read callback.
  12.295 + */
  12.296 +typedef enum {
  12.297 +
  12.298 +	FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
  12.299 +	/**< The read was OK and decoding can continue. */
  12.300 +
  12.301 +	FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
  12.302 +	/**< The read was attempted while at the end of the stream.  Note that
  12.303 +	 * the client must only return this value when the read callback was
  12.304 +	 * called when already at the end of the stream.  Otherwise, if the read
  12.305 +	 * itself moves to the end of the stream, the client should still return
  12.306 +	 * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
  12.307 +	 * the next read callback it should return
  12.308 +	 * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
  12.309 +	 * of \c 0.
  12.310 +	 */
  12.311 +
  12.312 +	FLAC__STREAM_DECODER_READ_STATUS_ABORT
  12.313 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  12.314 +
  12.315 +} FLAC__StreamDecoderReadStatus;
  12.316 +
  12.317 +/** Maps a FLAC__StreamDecoderReadStatus to a C string.
  12.318 + *
  12.319 + *  Using a FLAC__StreamDecoderReadStatus as the index to this array
  12.320 + *  will give the string equivalent.  The contents should not be modified.
  12.321 + */
  12.322 +extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
  12.323 +
  12.324 +
  12.325 +/** Return values for the FLAC__StreamDecoder seek callback.
  12.326 + */
  12.327 +typedef enum {
  12.328 +
  12.329 +	FLAC__STREAM_DECODER_SEEK_STATUS_OK,
  12.330 +	/**< The seek was OK and decoding can continue. */
  12.331 +
  12.332 +	FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
  12.333 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  12.334 +
  12.335 +	FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  12.336 +	/**< Client does not support seeking. */
  12.337 +
  12.338 +} FLAC__StreamDecoderSeekStatus;
  12.339 +
  12.340 +/** Maps a FLAC__StreamDecoderSeekStatus to a C string.
  12.341 + *
  12.342 + *  Using a FLAC__StreamDecoderSeekStatus as the index to this array
  12.343 + *  will give the string equivalent.  The contents should not be modified.
  12.344 + */
  12.345 +extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
  12.346 +
  12.347 +
  12.348 +/** Return values for the FLAC__StreamDecoder tell callback.
  12.349 + */
  12.350 +typedef enum {
  12.351 +
  12.352 +	FLAC__STREAM_DECODER_TELL_STATUS_OK,
  12.353 +	/**< The tell was OK and decoding can continue. */
  12.354 +
  12.355 +	FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
  12.356 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  12.357 +
  12.358 +	FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  12.359 +	/**< Client does not support telling the position. */
  12.360 +
  12.361 +} FLAC__StreamDecoderTellStatus;
  12.362 +
  12.363 +/** Maps a FLAC__StreamDecoderTellStatus to a C string.
  12.364 + *
  12.365 + *  Using a FLAC__StreamDecoderTellStatus as the index to this array
  12.366 + *  will give the string equivalent.  The contents should not be modified.
  12.367 + */
  12.368 +extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
  12.369 +
  12.370 +
  12.371 +/** Return values for the FLAC__StreamDecoder length callback.
  12.372 + */
  12.373 +typedef enum {
  12.374 +
  12.375 +	FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
  12.376 +	/**< The length call was OK and decoding can continue. */
  12.377 +
  12.378 +	FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
  12.379 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  12.380 +
  12.381 +	FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  12.382 +	/**< Client does not support reporting the length. */
  12.383 +
  12.384 +} FLAC__StreamDecoderLengthStatus;
  12.385 +
  12.386 +/** Maps a FLAC__StreamDecoderLengthStatus to a C string.
  12.387 + *
  12.388 + *  Using a FLAC__StreamDecoderLengthStatus as the index to this array
  12.389 + *  will give the string equivalent.  The contents should not be modified.
  12.390 + */
  12.391 +extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
  12.392 +
  12.393 +
  12.394 +/** Return values for the FLAC__StreamDecoder write callback.
  12.395 + */
  12.396 +typedef enum {
  12.397 +
  12.398 +	FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
  12.399 +	/**< The write was OK and decoding can continue. */
  12.400 +
  12.401 +	FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
  12.402 +	/**< An unrecoverable error occurred.  The decoder will return from the process call. */
  12.403 +
  12.404 +} FLAC__StreamDecoderWriteStatus;
  12.405 +
  12.406 +/** Maps a FLAC__StreamDecoderWriteStatus to a C string.
  12.407 + *
  12.408 + *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
  12.409 + *  will give the string equivalent.  The contents should not be modified.
  12.410 + */
  12.411 +extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
  12.412 +
  12.413 +
  12.414 +/** Possible values passed back to the FLAC__StreamDecoder error callback.
  12.415 + *  \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
  12.416 + *  all.  The rest could be caused by bad sync (false synchronization on
  12.417 + *  data that is not the start of a frame) or corrupted data.  The error
  12.418 + *  itself is the decoder's best guess at what happened assuming a correct
  12.419 + *  sync.  For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
  12.420 + *  could be caused by a correct sync on the start of a frame, but some
  12.421 + *  data in the frame header was corrupted.  Or it could be the result of
  12.422 + *  syncing on a point the stream that looked like the starting of a frame
  12.423 + *  but was not.  \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  12.424 + *  could be because the decoder encountered a valid frame made by a future
  12.425 + *  version of the encoder which it cannot parse, or because of a false
  12.426 + *  sync making it appear as though an encountered frame was generated by
  12.427 + *  a future encoder.
  12.428 + */
  12.429 +typedef enum {
  12.430 +
  12.431 +	FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
  12.432 +	/**< An error in the stream caused the decoder to lose synchronization. */
  12.433 +
  12.434 +	FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
  12.435 +	/**< The decoder encountered a corrupted frame header. */
  12.436 +
  12.437 +	FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
  12.438 +	/**< The frame's data did not match the CRC in the footer. */
  12.439 +
  12.440 +	FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  12.441 +	/**< The decoder encountered reserved fields in use in the stream. */
  12.442 +
  12.443 +} FLAC__StreamDecoderErrorStatus;
  12.444 +
  12.445 +/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
  12.446 + *
  12.447 + *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
  12.448 + *  will give the string equivalent.  The contents should not be modified.
  12.449 + */
  12.450 +extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
  12.451 +
  12.452 +
  12.453 +/***********************************************************************
  12.454 + *
  12.455 + * class FLAC__StreamDecoder
  12.456 + *
  12.457 + ***********************************************************************/
  12.458 +
  12.459 +struct FLAC__StreamDecoderProtected;
  12.460 +struct FLAC__StreamDecoderPrivate;
  12.461 +/** The opaque structure definition for the stream decoder type.
  12.462 + *  See the \link flac_stream_decoder stream decoder module \endlink
  12.463 + *  for a detailed description.
  12.464 + */
  12.465 +typedef struct {
  12.466 +	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  12.467 +	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  12.468 +} FLAC__StreamDecoder;
  12.469 +
  12.470 +/** Signature for the read callback.
  12.471 + *
  12.472 + *  A function pointer matching this signature must be passed to
  12.473 + *  FLAC__stream_decoder_init*_stream(). The supplied function will be
  12.474 + *  called when the decoder needs more input data.  The address of the
  12.475 + *  buffer to be filled is supplied, along with the number of bytes the
  12.476 + *  buffer can hold.  The callback may choose to supply less data and
  12.477 + *  modify the byte count but must be careful not to overflow the buffer.
  12.478 + *  The callback then returns a status code chosen from
  12.479 + *  FLAC__StreamDecoderReadStatus.
  12.480 + *
  12.481 + * Here is an example of a read callback for stdio streams:
  12.482 + * \code
  12.483 + * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  12.484 + * {
  12.485 + *   FILE *file = ((MyClientData*)client_data)->file;
  12.486 + *   if(*bytes > 0) {
  12.487 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  12.488 + *     if(ferror(file))
  12.489 + *       return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  12.490 + *     else if(*bytes == 0)
  12.491 + *       return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
  12.492 + *     else
  12.493 + *       return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
  12.494 + *   }
  12.495 + *   else
  12.496 + *     return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  12.497 + * }
  12.498 + * \endcode
  12.499 + *
  12.500 + * \note In general, FLAC__StreamDecoder functions which change the
  12.501 + * state should not be called on the \a decoder while in the callback.
  12.502 + *
  12.503 + * \param  decoder  The decoder instance calling the callback.
  12.504 + * \param  buffer   A pointer to a location for the callee to store
  12.505 + *                  data to be decoded.
  12.506 + * \param  bytes    A pointer to the size of the buffer.  On entry
  12.507 + *                  to the callback, it contains the maximum number
  12.508 + *                  of bytes that may be stored in \a buffer.  The
  12.509 + *                  callee must set it to the actual number of bytes
  12.510 + *                  stored (0 in case of error or end-of-stream) before
  12.511 + *                  returning.
  12.512 + * \param  client_data  The callee's client data set through
  12.513 + *                      FLAC__stream_decoder_init_*().
  12.514 + * \retval FLAC__StreamDecoderReadStatus
  12.515 + *    The callee's return status.  Note that the callback should return
  12.516 + *    \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
  12.517 + *    zero bytes were read and there is no more data to be read.
  12.518 + */
  12.519 +typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  12.520 +
  12.521 +/** Signature for the seek callback.
  12.522 + *
  12.523 + *  A function pointer matching this signature may be passed to
  12.524 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  12.525 + *  called when the decoder needs to seek the input stream.  The decoder
  12.526 + *  will pass the absolute byte offset to seek to, 0 meaning the
  12.527 + *  beginning of the stream.
  12.528 + *
  12.529 + * Here is an example of a seek callback for stdio streams:
  12.530 + * \code
  12.531 + * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  12.532 + * {
  12.533 + *   FILE *file = ((MyClientData*)client_data)->file;
  12.534 + *   if(file == stdin)
  12.535 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
  12.536 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  12.537 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
  12.538 + *   else
  12.539 + *     return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
  12.540 + * }
  12.541 + * \endcode
  12.542 + *
  12.543 + * \note In general, FLAC__StreamDecoder functions which change the
  12.544 + * state should not be called on the \a decoder while in the callback.
  12.545 + *
  12.546 + * \param  decoder  The decoder instance calling the callback.
  12.547 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  12.548 + *                               to seek to.
  12.549 + * \param  client_data  The callee's client data set through
  12.550 + *                      FLAC__stream_decoder_init_*().
  12.551 + * \retval FLAC__StreamDecoderSeekStatus
  12.552 + *    The callee's return status.
  12.553 + */
  12.554 +typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  12.555 +
  12.556 +/** Signature for the tell callback.
  12.557 + *
  12.558 + *  A function pointer matching this signature may be passed to
  12.559 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  12.560 + *  called when the decoder wants to know the current position of the
  12.561 + *  stream.  The callback should return the byte offset from the
  12.562 + *  beginning of the stream.
  12.563 + *
  12.564 + * Here is an example of a tell callback for stdio streams:
  12.565 + * \code
  12.566 + * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  12.567 + * {
  12.568 + *   FILE *file = ((MyClientData*)client_data)->file;
  12.569 + *   off_t pos;
  12.570 + *   if(file == stdin)
  12.571 + *     return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
  12.572 + *   else if((pos = ftello(file)) < 0)
  12.573 + *     return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
  12.574 + *   else {
  12.575 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  12.576 + *     return FLAC__STREAM_DECODER_TELL_STATUS_OK;
  12.577 + *   }
  12.578 + * }
  12.579 + * \endcode
  12.580 + *
  12.581 + * \note In general, FLAC__StreamDecoder functions which change the
  12.582 + * state should not be called on the \a decoder while in the callback.
  12.583 + *
  12.584 + * \param  decoder  The decoder instance calling the callback.
  12.585 + * \param  absolute_byte_offset  A pointer to storage for the current offset
  12.586 + *                               from the beginning of the stream.
  12.587 + * \param  client_data  The callee's client data set through
  12.588 + *                      FLAC__stream_decoder_init_*().
  12.589 + * \retval FLAC__StreamDecoderTellStatus
  12.590 + *    The callee's return status.
  12.591 + */
  12.592 +typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  12.593 +
  12.594 +/** Signature for the length callback.
  12.595 + *
  12.596 + *  A function pointer matching this signature may be passed to
  12.597 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  12.598 + *  called when the decoder wants to know the total length of the stream
  12.599 + *  in bytes.
  12.600 + *
  12.601 + * Here is an example of a length callback for stdio streams:
  12.602 + * \code
  12.603 + * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
  12.604 + * {
  12.605 + *   FILE *file = ((MyClientData*)client_data)->file;
  12.606 + *   struct stat filestats;
  12.607 + *
  12.608 + *   if(file == stdin)
  12.609 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
  12.610 + *   else if(fstat(fileno(file), &filestats) != 0)
  12.611 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
  12.612 + *   else {
  12.613 + *     *stream_length = (FLAC__uint64)filestats.st_size;
  12.614 + *     return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
  12.615 + *   }
  12.616 + * }
  12.617 + * \endcode
  12.618 + *
  12.619 + * \note In general, FLAC__StreamDecoder functions which change the
  12.620 + * state should not be called on the \a decoder while in the callback.
  12.621 + *
  12.622 + * \param  decoder  The decoder instance calling the callback.
  12.623 + * \param  stream_length  A pointer to storage for the length of the stream
  12.624 + *                        in bytes.
  12.625 + * \param  client_data  The callee's client data set through
  12.626 + *                      FLAC__stream_decoder_init_*().
  12.627 + * \retval FLAC__StreamDecoderLengthStatus
  12.628 + *    The callee's return status.
  12.629 + */
  12.630 +typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  12.631 +
  12.632 +/** Signature for the EOF callback.
  12.633 + *
  12.634 + *  A function pointer matching this signature may be passed to
  12.635 + *  FLAC__stream_decoder_init*_stream().  The supplied function will be
  12.636 + *  called when the decoder needs to know if the end of the stream has
  12.637 + *  been reached.
  12.638 + *
  12.639 + * Here is an example of a EOF callback for stdio streams:
  12.640 + * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
  12.641 + * \code
  12.642 + * {
  12.643 + *   FILE *file = ((MyClientData*)client_data)->file;
  12.644 + *   return feof(file)? true : false;
  12.645 + * }
  12.646 + * \endcode
  12.647 + *
  12.648 + * \note In general, FLAC__StreamDecoder functions which change the
  12.649 + * state should not be called on the \a decoder while in the callback.
  12.650 + *
  12.651 + * \param  decoder  The decoder instance calling the callback.
  12.652 + * \param  client_data  The callee's client data set through
  12.653 + *                      FLAC__stream_decoder_init_*().
  12.654 + * \retval FLAC__bool
  12.655 + *    \c true if the currently at the end of the stream, else \c false.
  12.656 + */
  12.657 +typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
  12.658 +
  12.659 +/** Signature for the write callback.
  12.660 + *
  12.661 + *  A function pointer matching this signature must be passed to one of
  12.662 + *  the FLAC__stream_decoder_init_*() functions.
  12.663 + *  The supplied function will be called when the decoder has decoded a
  12.664 + *  single audio frame.  The decoder will pass the frame metadata as well
  12.665 + *  as an array of pointers (one for each channel) pointing to the
  12.666 + *  decoded audio.
  12.667 + *
  12.668 + * \note In general, FLAC__StreamDecoder functions which change the
  12.669 + * state should not be called on the \a decoder while in the callback.
  12.670 + *
  12.671 + * \param  decoder  The decoder instance calling the callback.
  12.672 + * \param  frame    The description of the decoded frame.  See
  12.673 + *                  FLAC__Frame.
  12.674 + * \param  buffer   An array of pointers to decoded channels of data.
  12.675 + *                  Each pointer will point to an array of signed
  12.676 + *                  samples of length \a frame->header.blocksize.
  12.677 + *                  Channels will be ordered according to the FLAC
  12.678 + *                  specification; see the documentation for the
  12.679 + *                  <A HREF="../format.html#frame_header">frame header</A>.
  12.680 + * \param  client_data  The callee's client data set through
  12.681 + *                      FLAC__stream_decoder_init_*().
  12.682 + * \retval FLAC__StreamDecoderWriteStatus
  12.683 + *    The callee's return status.
  12.684 + */
  12.685 +typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  12.686 +
  12.687 +/** Signature for the metadata callback.
  12.688 + *
  12.689 + *  A function pointer matching this signature must be passed to one of
  12.690 + *  the FLAC__stream_decoder_init_*() functions.
  12.691 + *  The supplied function will be called when the decoder has decoded a
  12.692 + *  metadata block.  In a valid FLAC file there will always be one
  12.693 + *  \c STREAMINFO block, followed by zero or more other metadata blocks.
  12.694 + *  These will be supplied by the decoder in the same order as they
  12.695 + *  appear in the stream and always before the first audio frame (i.e.
  12.696 + *  write callback).  The metadata block that is passed in must not be
  12.697 + *  modified, and it doesn't live beyond the callback, so you should make
  12.698 + *  a copy of it with FLAC__metadata_object_clone() if you will need it
  12.699 + *  elsewhere.  Since metadata blocks can potentially be large, by
  12.700 + *  default the decoder only calls the metadata callback for the
  12.701 + *  \c STREAMINFO block; you can instruct the decoder to pass or filter
  12.702 + *  other blocks with FLAC__stream_decoder_set_metadata_*() calls.
  12.703 + *
  12.704 + * \note In general, FLAC__StreamDecoder functions which change the
  12.705 + * state should not be called on the \a decoder while in the callback.
  12.706 + *
  12.707 + * \param  decoder  The decoder instance calling the callback.
  12.708 + * \param  metadata The decoded metadata block.
  12.709 + * \param  client_data  The callee's client data set through
  12.710 + *                      FLAC__stream_decoder_init_*().
  12.711 + */
  12.712 +typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  12.713 +
  12.714 +/** Signature for the error callback.
  12.715 + *
  12.716 + *  A function pointer matching this signature must be passed to one of
  12.717 + *  the FLAC__stream_decoder_init_*() functions.
  12.718 + *  The supplied function will be called whenever an error occurs during
  12.719 + *  decoding.
  12.720 + *
  12.721 + * \note In general, FLAC__StreamDecoder functions which change the
  12.722 + * state should not be called on the \a decoder while in the callback.
  12.723 + *
  12.724 + * \param  decoder  The decoder instance calling the callback.
  12.725 + * \param  status   The error encountered by the decoder.
  12.726 + * \param  client_data  The callee's client data set through
  12.727 + *                      FLAC__stream_decoder_init_*().
  12.728 + */
  12.729 +typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  12.730 +
  12.731 +
  12.732 +/***********************************************************************
  12.733 + *
  12.734 + * Class constructor/destructor
  12.735 + *
  12.736 + ***********************************************************************/
  12.737 +
  12.738 +/** Create a new stream decoder instance.  The instance is created with
  12.739 + *  default settings; see the individual FLAC__stream_decoder_set_*()
  12.740 + *  functions for each setting's default.
  12.741 + *
  12.742 + * \retval FLAC__StreamDecoder*
  12.743 + *    \c NULL if there was an error allocating memory, else the new instance.
  12.744 + */
  12.745 +FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
  12.746 +
  12.747 +/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  12.748 + *
  12.749 + * \param decoder  A pointer to an existing decoder.
  12.750 + * \assert
  12.751 + *    \code decoder != NULL \endcode
  12.752 + */
  12.753 +FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  12.754 +
  12.755 +
  12.756 +/***********************************************************************
  12.757 + *
  12.758 + * Public class method prototypes
  12.759 + *
  12.760 + ***********************************************************************/
  12.761 +
  12.762 +/** Set the serial number for the FLAC stream within the Ogg container.
  12.763 + *  The default behavior is to use the serial number of the first Ogg
  12.764 + *  page.  Setting a serial number here will explicitly specify which
  12.765 + *  stream is to be decoded.
  12.766 + *
  12.767 + * \note
  12.768 + * This does not need to be set for native FLAC decoding.
  12.769 + *
  12.770 + * \default \c use serial number of first page
  12.771 + * \param  decoder        A decoder instance to set.
  12.772 + * \param  serial_number  See above.
  12.773 + * \assert
  12.774 + *    \code decoder != NULL \endcode
  12.775 + * \retval FLAC__bool
  12.776 + *    \c false if the decoder is already initialized, else \c true.
  12.777 + */
  12.778 +FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
  12.779 +
  12.780 +/** Set the "MD5 signature checking" flag.  If \c true, the decoder will
  12.781 + *  compute the MD5 signature of the unencoded audio data while decoding
  12.782 + *  and compare it to the signature from the STREAMINFO block, if it
  12.783 + *  exists, during FLAC__stream_decoder_finish().
  12.784 + *
  12.785 + *  MD5 signature checking will be turned off (until the next
  12.786 + *  FLAC__stream_decoder_reset()) if there is no signature in the
  12.787 + *  STREAMINFO block or when a seek is attempted.
  12.788 + *
  12.789 + *  Clients that do not use the MD5 check should leave this off to speed
  12.790 + *  up decoding.
  12.791 + *
  12.792 + * \default \c false
  12.793 + * \param  decoder  A decoder instance to set.
  12.794 + * \param  value    Flag value (see above).
  12.795 + * \assert
  12.796 + *    \code decoder != NULL \endcode
  12.797 + * \retval FLAC__bool
  12.798 + *    \c false if the decoder is already initialized, else \c true.
  12.799 + */
  12.800 +FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
  12.801 +
  12.802 +/** Direct the decoder to pass on all metadata blocks of type \a type.
  12.803 + *
  12.804 + * \default By default, only the \c STREAMINFO block is returned via the
  12.805 + *          metadata callback.
  12.806 + * \param  decoder  A decoder instance to set.
  12.807 + * \param  type     See above.
  12.808 + * \assert
  12.809 + *    \code decoder != NULL \endcode
  12.810 + *    \a type is valid
  12.811 + * \retval FLAC__bool
  12.812 + *    \c false if the decoder is already initialized, else \c true.
  12.813 + */
  12.814 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  12.815 +
  12.816 +/** Direct the decoder to pass on all APPLICATION metadata blocks of the
  12.817 + *  given \a id.
  12.818 + *
  12.819 + * \default By default, only the \c STREAMINFO block is returned via the
  12.820 + *          metadata callback.
  12.821 + * \param  decoder  A decoder instance to set.
  12.822 + * \param  id       See above.
  12.823 + * \assert
  12.824 + *    \code decoder != NULL \endcode
  12.825 + *    \code id != NULL \endcode
  12.826 + * \retval FLAC__bool
  12.827 + *    \c false if the decoder is already initialized, else \c true.
  12.828 + */
  12.829 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  12.830 +
  12.831 +/** Direct the decoder to pass on all metadata blocks of any type.
  12.832 + *
  12.833 + * \default By default, only the \c STREAMINFO block is returned via the
  12.834 + *          metadata callback.
  12.835 + * \param  decoder  A decoder instance to set.
  12.836 + * \assert
  12.837 + *    \code decoder != NULL \endcode
  12.838 + * \retval FLAC__bool
  12.839 + *    \c false if the decoder is already initialized, else \c true.
  12.840 + */
  12.841 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
  12.842 +
  12.843 +/** Direct the decoder to filter out all metadata blocks of type \a type.
  12.844 + *
  12.845 + * \default By default, only the \c STREAMINFO block is returned via the
  12.846 + *          metadata callback.
  12.847 + * \param  decoder  A decoder instance to set.
  12.848 + * \param  type     See above.
  12.849 + * \assert
  12.850 + *    \code decoder != NULL \endcode
  12.851 + *    \a type is valid
  12.852 + * \retval FLAC__bool
  12.853 + *    \c false if the decoder is already initialized, else \c true.
  12.854 + */
  12.855 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  12.856 +
  12.857 +/** Direct the decoder to filter out all APPLICATION metadata blocks of
  12.858 + *  the given \a id.
  12.859 + *
  12.860 + * \default By default, only the \c STREAMINFO block is returned via the
  12.861 + *          metadata callback.
  12.862 + * \param  decoder  A decoder instance to set.
  12.863 + * \param  id       See above.
  12.864 + * \assert
  12.865 + *    \code decoder != NULL \endcode
  12.866 + *    \code id != NULL \endcode
  12.867 + * \retval FLAC__bool
  12.868 + *    \c false if the decoder is already initialized, else \c true.
  12.869 + */
  12.870 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  12.871 +
  12.872 +/** Direct the decoder to filter out all metadata blocks of any type.
  12.873 + *
  12.874 + * \default By default, only the \c STREAMINFO block is returned via the
  12.875 + *          metadata callback.
  12.876 + * \param  decoder  A decoder instance to set.
  12.877 + * \assert
  12.878 + *    \code decoder != NULL \endcode
  12.879 + * \retval FLAC__bool
  12.880 + *    \c false if the decoder is already initialized, else \c true.
  12.881 + */
  12.882 +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
  12.883 +
  12.884 +/** Get the current decoder state.
  12.885 + *
  12.886 + * \param  decoder  A decoder instance to query.
  12.887 + * \assert
  12.888 + *    \code decoder != NULL \endcode
  12.889 + * \retval FLAC__StreamDecoderState
  12.890 + *    The current decoder state.
  12.891 + */
  12.892 +FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
  12.893 +
  12.894 +/** Get the current decoder state as a C string.
  12.895 + *
  12.896 + * \param  decoder  A decoder instance to query.
  12.897 + * \assert
  12.898 + *    \code decoder != NULL \endcode
  12.899 + * \retval const char *
  12.900 + *    The decoder state as a C string.  Do not modify the contents.
  12.901 + */
  12.902 +FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
  12.903 +
  12.904 +/** Get the "MD5 signature checking" flag.
  12.905 + *  This is the value of the setting, not whether or not the decoder is
  12.906 + *  currently checking the MD5 (remember, it can be turned off automatically
  12.907 + *  by a seek).  When the decoder is reset the flag will be restored to the
  12.908 + *  value returned by this function.
  12.909 + *
  12.910 + * \param  decoder  A decoder instance to query.
  12.911 + * \assert
  12.912 + *    \code decoder != NULL \endcode
  12.913 + * \retval FLAC__bool
  12.914 + *    See above.
  12.915 + */
  12.916 +FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
  12.917 +
  12.918 +/** Get the total number of samples in the stream being decoded.
  12.919 + *  Will only be valid after decoding has started and will contain the
  12.920 + *  value from the \c STREAMINFO block.  A value of \c 0 means "unknown".
  12.921 + *
  12.922 + * \param  decoder  A decoder instance to query.
  12.923 + * \assert
  12.924 + *    \code decoder != NULL \endcode
  12.925 + * \retval unsigned
  12.926 + *    See above.
  12.927 + */
  12.928 +FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
  12.929 +
  12.930 +/** Get the current number of channels in the stream being decoded.
  12.931 + *  Will only be valid after decoding has started and will contain the
  12.932 + *  value from the most recently decoded frame header.
  12.933 + *
  12.934 + * \param  decoder  A decoder instance to query.
  12.935 + * \assert
  12.936 + *    \code decoder != NULL \endcode
  12.937 + * \retval unsigned
  12.938 + *    See above.
  12.939 + */
  12.940 +FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
  12.941 +
  12.942 +/** Get the current channel assignment in the stream being decoded.
  12.943 + *  Will only be valid after decoding has started and will contain the
  12.944 + *  value from the most recently decoded frame header.
  12.945 + *
  12.946 + * \param  decoder  A decoder instance to query.
  12.947 + * \assert
  12.948 + *    \code decoder != NULL \endcode
  12.949 + * \retval FLAC__ChannelAssignment
  12.950 + *    See above.
  12.951 + */
  12.952 +FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
  12.953 +
  12.954 +/** Get the current sample resolution in the stream being decoded.
  12.955 + *  Will only be valid after decoding has started and will contain the
  12.956 + *  value from the most recently decoded frame header.
  12.957 + *
  12.958 + * \param  decoder  A decoder instance to query.
  12.959 + * \assert
  12.960 + *    \code decoder != NULL \endcode
  12.961 + * \retval unsigned
  12.962 + *    See above.
  12.963 + */
  12.964 +FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
  12.965 +
  12.966 +/** Get the current sample rate in Hz of the stream being decoded.
  12.967 + *  Will only be valid after decoding has started and will contain the
  12.968 + *  value from the most recently decoded frame header.
  12.969 + *
  12.970 + * \param  decoder  A decoder instance to query.
  12.971 + * \assert
  12.972 + *    \code decoder != NULL \endcode
  12.973 + * \retval unsigned
  12.974 + *    See above.
  12.975 + */
  12.976 +FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
  12.977 +
  12.978 +/** Get the current blocksize of the stream being decoded.
  12.979 + *  Will only be valid after decoding has started and will contain the
  12.980 + *  value from the most recently decoded frame header.
  12.981 + *
  12.982 + * \param  decoder  A decoder instance to query.
  12.983 + * \assert
  12.984 + *    \code decoder != NULL \endcode
  12.985 + * \retval unsigned
  12.986 + *    See above.
  12.987 + */
  12.988 +FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
  12.989 +
  12.990 +/** Returns the decoder's current read position within the stream.
  12.991 + *  The position is the byte offset from the start of the stream.
  12.992 + *  Bytes before this position have been fully decoded.  Note that
  12.993 + *  there may still be undecoded bytes in the decoder's read FIFO.
  12.994 + *  The returned position is correct even after a seek.
  12.995 + *
  12.996 + *  \warning This function currently only works for native FLAC,
  12.997 + *           not Ogg FLAC streams.
  12.998 + *
  12.999 + * \param  decoder   A decoder instance to query.
 12.1000 + * \param  position  Address at which to return the desired position.
 12.1001 + * \assert
 12.1002 + *    \code decoder != NULL \endcode
 12.1003 + *    \code position != NULL \endcode
 12.1004 + * \retval FLAC__bool
 12.1005 + *    \c true if successful, \c false if the stream is not native FLAC,
 12.1006 + *    or there was an error from the 'tell' callback or it returned
 12.1007 + *    \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
 12.1008 + */
 12.1009 +FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
 12.1010 +
 12.1011 +/** Initialize the decoder instance to decode native FLAC streams.
 12.1012 + *
 12.1013 + *  This flavor of initialization sets up the decoder to decode from a
 12.1014 + *  native FLAC stream. I/O is performed via callbacks to the client.
 12.1015 + *  For decoding from a plain file via filename or open FILE*,
 12.1016 + *  FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
 12.1017 + *  provide a simpler interface.
 12.1018 + *
 12.1019 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1020 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1021 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1022 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1023 + *  if initialization succeeded.
 12.1024 + *
 12.1025 + * \param  decoder            An uninitialized decoder instance.
 12.1026 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 12.1027 + *                            pointer must not be \c NULL.
 12.1028 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 12.1029 + *                            pointer may be \c NULL if seeking is not
 12.1030 + *                            supported.  If \a seek_callback is not \c NULL then a
 12.1031 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 12.1032 + *                            Alternatively, a dummy seek callback that just
 12.1033 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 12.1034 + *                            may also be supplied, all though this is slightly
 12.1035 + *                            less efficient for the decoder.
 12.1036 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 12.1037 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1038 + *                            \a seek_callback is not \c NULL then a
 12.1039 + *                            \a tell_callback must also be supplied.
 12.1040 + *                            Alternatively, a dummy tell callback that just
 12.1041 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 12.1042 + *                            may also be supplied, all though this is slightly
 12.1043 + *                            less efficient for the decoder.
 12.1044 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 12.1045 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1046 + *                            \a seek_callback is not \c NULL then a
 12.1047 + *                            \a length_callback must also be supplied.
 12.1048 + *                            Alternatively, a dummy length callback that just
 12.1049 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 12.1050 + *                            may also be supplied, all though this is slightly
 12.1051 + *                            less efficient for the decoder.
 12.1052 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 12.1053 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1054 + *                            \a seek_callback is not \c NULL then a
 12.1055 + *                            \a eof_callback must also be supplied.
 12.1056 + *                            Alternatively, a dummy length callback that just
 12.1057 + *                            returns \c false
 12.1058 + *                            may also be supplied, all though this is slightly
 12.1059 + *                            less efficient for the decoder.
 12.1060 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1061 + *                            pointer must not be \c NULL.
 12.1062 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1063 + *                            pointer may be \c NULL if the callback is not
 12.1064 + *                            desired.
 12.1065 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1066 + *                            pointer must not be \c NULL.
 12.1067 + * \param  client_data        This value will be supplied to callbacks in their
 12.1068 + *                            \a client_data argument.
 12.1069 + * \assert
 12.1070 + *    \code decoder != NULL \endcode
 12.1071 + * \retval FLAC__StreamDecoderInitStatus
 12.1072 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1073 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1074 + */
 12.1075 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
 12.1076 +	FLAC__StreamDecoder *decoder,
 12.1077 +	FLAC__StreamDecoderReadCallback read_callback,
 12.1078 +	FLAC__StreamDecoderSeekCallback seek_callback,
 12.1079 +	FLAC__StreamDecoderTellCallback tell_callback,
 12.1080 +	FLAC__StreamDecoderLengthCallback length_callback,
 12.1081 +	FLAC__StreamDecoderEofCallback eof_callback,
 12.1082 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1083 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1084 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1085 +	void *client_data
 12.1086 +);
 12.1087 +
 12.1088 +/** Initialize the decoder instance to decode Ogg FLAC streams.
 12.1089 + *
 12.1090 + *  This flavor of initialization sets up the decoder to decode from a
 12.1091 + *  FLAC stream in an Ogg container. I/O is performed via callbacks to the
 12.1092 + *  client.  For decoding from a plain file via filename or open FILE*,
 12.1093 + *  FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
 12.1094 + *  provide a simpler interface.
 12.1095 + *
 12.1096 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1097 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1098 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1099 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1100 + *  if initialization succeeded.
 12.1101 + *
 12.1102 + *  \note Support for Ogg FLAC in the library is optional.  If this
 12.1103 + *  library has been built without support for Ogg FLAC, this function
 12.1104 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 12.1105 + *
 12.1106 + * \param  decoder            An uninitialized decoder instance.
 12.1107 + * \param  read_callback      See FLAC__StreamDecoderReadCallback.  This
 12.1108 + *                            pointer must not be \c NULL.
 12.1109 + * \param  seek_callback      See FLAC__StreamDecoderSeekCallback.  This
 12.1110 + *                            pointer may be \c NULL if seeking is not
 12.1111 + *                            supported.  If \a seek_callback is not \c NULL then a
 12.1112 + *                            \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
 12.1113 + *                            Alternatively, a dummy seek callback that just
 12.1114 + *                            returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
 12.1115 + *                            may also be supplied, all though this is slightly
 12.1116 + *                            less efficient for the decoder.
 12.1117 + * \param  tell_callback      See FLAC__StreamDecoderTellCallback.  This
 12.1118 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1119 + *                            \a seek_callback is not \c NULL then a
 12.1120 + *                            \a tell_callback must also be supplied.
 12.1121 + *                            Alternatively, a dummy tell callback that just
 12.1122 + *                            returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
 12.1123 + *                            may also be supplied, all though this is slightly
 12.1124 + *                            less efficient for the decoder.
 12.1125 + * \param  length_callback    See FLAC__StreamDecoderLengthCallback.  This
 12.1126 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1127 + *                            \a seek_callback is not \c NULL then a
 12.1128 + *                            \a length_callback must also be supplied.
 12.1129 + *                            Alternatively, a dummy length callback that just
 12.1130 + *                            returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
 12.1131 + *                            may also be supplied, all though this is slightly
 12.1132 + *                            less efficient for the decoder.
 12.1133 + * \param  eof_callback       See FLAC__StreamDecoderEofCallback.  This
 12.1134 + *                            pointer may be \c NULL if not supported by the client.  If
 12.1135 + *                            \a seek_callback is not \c NULL then a
 12.1136 + *                            \a eof_callback must also be supplied.
 12.1137 + *                            Alternatively, a dummy length callback that just
 12.1138 + *                            returns \c false
 12.1139 + *                            may also be supplied, all though this is slightly
 12.1140 + *                            less efficient for the decoder.
 12.1141 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1142 + *                            pointer must not be \c NULL.
 12.1143 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1144 + *                            pointer may be \c NULL if the callback is not
 12.1145 + *                            desired.
 12.1146 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1147 + *                            pointer must not be \c NULL.
 12.1148 + * \param  client_data        This value will be supplied to callbacks in their
 12.1149 + *                            \a client_data argument.
 12.1150 + * \assert
 12.1151 + *    \code decoder != NULL \endcode
 12.1152 + * \retval FLAC__StreamDecoderInitStatus
 12.1153 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1154 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1155 + */
 12.1156 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
 12.1157 +	FLAC__StreamDecoder *decoder,
 12.1158 +	FLAC__StreamDecoderReadCallback read_callback,
 12.1159 +	FLAC__StreamDecoderSeekCallback seek_callback,
 12.1160 +	FLAC__StreamDecoderTellCallback tell_callback,
 12.1161 +	FLAC__StreamDecoderLengthCallback length_callback,
 12.1162 +	FLAC__StreamDecoderEofCallback eof_callback,
 12.1163 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1164 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1165 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1166 +	void *client_data
 12.1167 +);
 12.1168 +
 12.1169 +/** Initialize the decoder instance to decode native FLAC files.
 12.1170 + *
 12.1171 + *  This flavor of initialization sets up the decoder to decode from a
 12.1172 + *  plain native FLAC file.  For non-stdio streams, you must use
 12.1173 + *  FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
 12.1174 + *
 12.1175 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1176 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1177 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1178 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1179 + *  if initialization succeeded.
 12.1180 + *
 12.1181 + * \param  decoder            An uninitialized decoder instance.
 12.1182 + * \param  file               An open FLAC file.  The file should have been
 12.1183 + *                            opened with mode \c "rb" and rewound.  The file
 12.1184 + *                            becomes owned by the decoder and should not be
 12.1185 + *                            manipulated by the client while decoding.
 12.1186 + *                            Unless \a file is \c stdin, it will be closed
 12.1187 + *                            when FLAC__stream_decoder_finish() is called.
 12.1188 + *                            Note however that seeking will not work when
 12.1189 + *                            decoding from \c stdout since it is not seekable.
 12.1190 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1191 + *                            pointer must not be \c NULL.
 12.1192 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1193 + *                            pointer may be \c NULL if the callback is not
 12.1194 + *                            desired.
 12.1195 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1196 + *                            pointer must not be \c NULL.
 12.1197 + * \param  client_data        This value will be supplied to callbacks in their
 12.1198 + *                            \a client_data argument.
 12.1199 + * \assert
 12.1200 + *    \code decoder != NULL \endcode
 12.1201 + *    \code file != NULL \endcode
 12.1202 + * \retval FLAC__StreamDecoderInitStatus
 12.1203 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1204 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1205 + */
 12.1206 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
 12.1207 +	FLAC__StreamDecoder *decoder,
 12.1208 +	FILE *file,
 12.1209 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1210 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1211 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1212 +	void *client_data
 12.1213 +);
 12.1214 +
 12.1215 +/** Initialize the decoder instance to decode Ogg FLAC files.
 12.1216 + *
 12.1217 + *  This flavor of initialization sets up the decoder to decode from a
 12.1218 + *  plain Ogg FLAC file.  For non-stdio streams, you must use
 12.1219 + *  FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
 12.1220 + *
 12.1221 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1222 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1223 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1224 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1225 + *  if initialization succeeded.
 12.1226 + *
 12.1227 + *  \note Support for Ogg FLAC in the library is optional.  If this
 12.1228 + *  library has been built without support for Ogg FLAC, this function
 12.1229 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 12.1230 + *
 12.1231 + * \param  decoder            An uninitialized decoder instance.
 12.1232 + * \param  file               An open FLAC file.  The file should have been
 12.1233 + *                            opened with mode \c "rb" and rewound.  The file
 12.1234 + *                            becomes owned by the decoder and should not be
 12.1235 + *                            manipulated by the client while decoding.
 12.1236 + *                            Unless \a file is \c stdin, it will be closed
 12.1237 + *                            when FLAC__stream_decoder_finish() is called.
 12.1238 + *                            Note however that seeking will not work when
 12.1239 + *                            decoding from \c stdout since it is not seekable.
 12.1240 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1241 + *                            pointer must not be \c NULL.
 12.1242 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1243 + *                            pointer may be \c NULL if the callback is not
 12.1244 + *                            desired.
 12.1245 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1246 + *                            pointer must not be \c NULL.
 12.1247 + * \param  client_data        This value will be supplied to callbacks in their
 12.1248 + *                            \a client_data argument.
 12.1249 + * \assert
 12.1250 + *    \code decoder != NULL \endcode
 12.1251 + *    \code file != NULL \endcode
 12.1252 + * \retval FLAC__StreamDecoderInitStatus
 12.1253 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1254 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1255 + */
 12.1256 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
 12.1257 +	FLAC__StreamDecoder *decoder,
 12.1258 +	FILE *file,
 12.1259 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1260 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1261 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1262 +	void *client_data
 12.1263 +);
 12.1264 +
 12.1265 +/** Initialize the decoder instance to decode native FLAC files.
 12.1266 + *
 12.1267 + *  This flavor of initialization sets up the decoder to decode from a plain
 12.1268 + *  native FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 12.1269 + *  example, with Unicode filenames on Windows), you must use
 12.1270 + *  FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
 12.1271 + *  and provide callbacks for the I/O.
 12.1272 + *
 12.1273 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1274 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1275 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1276 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1277 + *  if initialization succeeded.
 12.1278 + *
 12.1279 + * \param  decoder            An uninitialized decoder instance.
 12.1280 + * \param  filename           The name of the file to decode from.  The file will
 12.1281 + *                            be opened with fopen().  Use \c NULL to decode from
 12.1282 + *                            \c stdin.  Note that \c stdin is not seekable.
 12.1283 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1284 + *                            pointer must not be \c NULL.
 12.1285 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1286 + *                            pointer may be \c NULL if the callback is not
 12.1287 + *                            desired.
 12.1288 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1289 + *                            pointer must not be \c NULL.
 12.1290 + * \param  client_data        This value will be supplied to callbacks in their
 12.1291 + *                            \a client_data argument.
 12.1292 + * \assert
 12.1293 + *    \code decoder != NULL \endcode
 12.1294 + * \retval FLAC__StreamDecoderInitStatus
 12.1295 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1296 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1297 + */
 12.1298 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
 12.1299 +	FLAC__StreamDecoder *decoder,
 12.1300 +	const char *filename,
 12.1301 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1302 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1303 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1304 +	void *client_data
 12.1305 +);
 12.1306 +
 12.1307 +/** Initialize the decoder instance to decode Ogg FLAC files.
 12.1308 + *
 12.1309 + *  This flavor of initialization sets up the decoder to decode from a plain
 12.1310 + *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient, (for
 12.1311 + *  example, with Unicode filenames on Windows), you must use
 12.1312 + *  FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
 12.1313 + *  and provide callbacks for the I/O.
 12.1314 + *
 12.1315 + *  This function should be called after FLAC__stream_decoder_new() and
 12.1316 + *  FLAC__stream_decoder_set_*() but before any of the
 12.1317 + *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 12.1318 + *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 12.1319 + *  if initialization succeeded.
 12.1320 + *
 12.1321 + *  \note Support for Ogg FLAC in the library is optional.  If this
 12.1322 + *  library has been built without support for Ogg FLAC, this function
 12.1323 + *  will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
 12.1324 + *
 12.1325 + * \param  decoder            An uninitialized decoder instance.
 12.1326 + * \param  filename           The name of the file to decode from.  The file will
 12.1327 + *                            be opened with fopen().  Use \c NULL to decode from
 12.1328 + *                            \c stdin.  Note that \c stdin is not seekable.
 12.1329 + * \param  write_callback     See FLAC__StreamDecoderWriteCallback.  This
 12.1330 + *                            pointer must not be \c NULL.
 12.1331 + * \param  metadata_callback  See FLAC__StreamDecoderMetadataCallback.  This
 12.1332 + *                            pointer may be \c NULL if the callback is not
 12.1333 + *                            desired.
 12.1334 + * \param  error_callback     See FLAC__StreamDecoderErrorCallback.  This
 12.1335 + *                            pointer must not be \c NULL.
 12.1336 + * \param  client_data        This value will be supplied to callbacks in their
 12.1337 + *                            \a client_data argument.
 12.1338 + * \assert
 12.1339 + *    \code decoder != NULL \endcode
 12.1340 + * \retval FLAC__StreamDecoderInitStatus
 12.1341 + *    \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
 12.1342 + *    see FLAC__StreamDecoderInitStatus for the meanings of other return values.
 12.1343 + */
 12.1344 +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
 12.1345 +	FLAC__StreamDecoder *decoder,
 12.1346 +	const char *filename,
 12.1347 +	FLAC__StreamDecoderWriteCallback write_callback,
 12.1348 +	FLAC__StreamDecoderMetadataCallback metadata_callback,
 12.1349 +	FLAC__StreamDecoderErrorCallback error_callback,
 12.1350 +	void *client_data
 12.1351 +);
 12.1352 +
 12.1353 +/** Finish the decoding process.
 12.1354 + *  Flushes the decoding buffer, releases resources, resets the decoder
 12.1355 + *  settings to their defaults, and returns the decoder state to
 12.1356 + *  FLAC__STREAM_DECODER_UNINITIALIZED.
 12.1357 + *
 12.1358 + *  In the event of a prematurely-terminated decode, it is not strictly
 12.1359 + *  necessary to call this immediately before FLAC__stream_decoder_delete()
 12.1360 + *  but it is good practice to match every FLAC__stream_decoder_init_*()
 12.1361 + *  with a FLAC__stream_decoder_finish().
 12.1362 + *
 12.1363 + * \param  decoder  An uninitialized decoder instance.
 12.1364 + * \assert
 12.1365 + *    \code decoder != NULL \endcode
 12.1366 + * \retval FLAC__bool
 12.1367 + *    \c false if MD5 checking is on AND a STREAMINFO block was available
 12.1368 + *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
 12.1369 + *    signature does not match the one computed by the decoder; else
 12.1370 + *    \c true.
 12.1371 + */
 12.1372 +FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
 12.1373 +
 12.1374 +/** Flush the stream input.
 12.1375 + *  The decoder's input buffer will be cleared and the state set to
 12.1376 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.  This will also turn
 12.1377 + *  off MD5 checking.
 12.1378 + *
 12.1379 + * \param  decoder  A decoder instance.
 12.1380 + * \assert
 12.1381 + *    \code decoder != NULL \endcode
 12.1382 + * \retval FLAC__bool
 12.1383 + *    \c true if successful, else \c false if a memory allocation
 12.1384 + *    error occurs (in which case the state will be set to
 12.1385 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
 12.1386 + */
 12.1387 +FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
 12.1388 +
 12.1389 +/** Reset the decoding process.
 12.1390 + *  The decoder's input buffer will be cleared and the state set to
 12.1391 + *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
 12.1392 + *  FLAC__stream_decoder_finish() except that the settings are
 12.1393 + *  preserved; there is no need to call FLAC__stream_decoder_init_*()
 12.1394 + *  before decoding again.  MD5 checking will be restored to its original
 12.1395 + *  setting.
 12.1396 + *
 12.1397 + *  If the decoder is seekable, or was initialized with
 12.1398 + *  FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
 12.1399 + *  the decoder will also attempt to seek to the beginning of the file.
 12.1400 + *  If this rewind fails, this function will return \c false.  It follows
 12.1401 + *  that FLAC__stream_decoder_reset() cannot be used when decoding from
 12.1402 + *  \c stdin.
 12.1403 + *
 12.1404 + *  If the decoder was initialized with FLAC__stream_encoder_init*_stream()
 12.1405 + *  and is not seekable (i.e. no seek callback was provided or the seek
 12.1406 + *  callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
 12.1407 + *  is the duty of the client to start feeding data from the beginning of
 12.1408 + *  the stream on the next FLAC__stream_decoder_process() or
 12.1409 + *  FLAC__stream_decoder_process_interleaved() call.
 12.1410 + *
 12.1411 + * \param  decoder  A decoder instance.
 12.1412 + * \assert
 12.1413 + *    \code decoder != NULL \endcode
 12.1414 + * \retval FLAC__bool
 12.1415 + *    \c true if successful, else \c false if a memory allocation occurs
 12.1416 + *    (in which case the state will be set to
 12.1417 + *    \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
 12.1418 + *    occurs (the state will be unchanged).
 12.1419 + */
 12.1420 +FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
 12.1421 +
 12.1422 +/** Decode one metadata block or audio frame.
 12.1423 + *  This version instructs the decoder to decode a either a single metadata
 12.1424 + *  block or a single frame and stop, unless the callbacks return a fatal
 12.1425 + *  error or the read callback returns
 12.1426 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 12.1427 + *
 12.1428 + *  As the decoder needs more input it will call the read callback.
 12.1429 + *  Depending on what was decoded, the metadata or write callback will be
 12.1430 + *  called with the decoded metadata block or audio frame.
 12.1431 + *
 12.1432 + *  Unless there is a fatal read error or end of stream, this function
 12.1433 + *  will return once one whole frame is decoded.  In other words, if the
 12.1434 + *  stream is not synchronized or points to a corrupt frame header, the
 12.1435 + *  decoder will continue to try and resync until it gets to a valid
 12.1436 + *  frame, then decode one frame, then return.  If the decoder points to
 12.1437 + *  a frame whose frame CRC in the frame footer does not match the
 12.1438 + *  computed frame CRC, this function will issue a
 12.1439 + *  FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
 12.1440 + *  error callback, and return, having decoded one complete, although
 12.1441 + *  corrupt, frame.  (Such corrupted frames are sent as silence of the
 12.1442 + *  correct length to the write callback.)
 12.1443 + *
 12.1444 + * \param  decoder  An initialized decoder instance.
 12.1445 + * \assert
 12.1446 + *    \code decoder != NULL \endcode
 12.1447 + * \retval FLAC__bool
 12.1448 + *    \c false if any fatal read, write, or memory allocation error
 12.1449 + *    occurred (meaning decoding must stop), else \c true; for more
 12.1450 + *    information about the decoder, check the decoder state with
 12.1451 + *    FLAC__stream_decoder_get_state().
 12.1452 + */
 12.1453 +FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
 12.1454 +
 12.1455 +/** Decode until the end of the metadata.
 12.1456 + *  This version instructs the decoder to decode from the current position
 12.1457 + *  and continue until all the metadata has been read, or until the
 12.1458 + *  callbacks return a fatal error or the read callback returns
 12.1459 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 12.1460 + *
 12.1461 + *  As the decoder needs more input it will call the read callback.
 12.1462 + *  As each metadata block is decoded, the metadata callback will be called
 12.1463 + *  with the decoded metadata.
 12.1464 + *
 12.1465 + * \param  decoder  An initialized decoder instance.
 12.1466 + * \assert
 12.1467 + *    \code decoder != NULL \endcode
 12.1468 + * \retval FLAC__bool
 12.1469 + *    \c false if any fatal read, write, or memory allocation error
 12.1470 + *    occurred (meaning decoding must stop), else \c true; for more
 12.1471 + *    information about the decoder, check the decoder state with
 12.1472 + *    FLAC__stream_decoder_get_state().
 12.1473 + */
 12.1474 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
 12.1475 +
 12.1476 +/** Decode until the end of the stream.
 12.1477 + *  This version instructs the decoder to decode from the current position
 12.1478 + *  and continue until the end of stream (the read callback returns
 12.1479 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
 12.1480 + *  callbacks return a fatal error.
 12.1481 + *
 12.1482 + *  As the decoder needs more input it will call the read callback.
 12.1483 + *  As each metadata block and frame is decoded, the metadata or write
 12.1484 + *  callback will be called with the decoded metadata or frame.
 12.1485 + *
 12.1486 + * \param  decoder  An initialized decoder instance.
 12.1487 + * \assert
 12.1488 + *    \code decoder != NULL \endcode
 12.1489 + * \retval FLAC__bool
 12.1490 + *    \c false if any fatal read, write, or memory allocation error
 12.1491 + *    occurred (meaning decoding must stop), else \c true; for more
 12.1492 + *    information about the decoder, check the decoder state with
 12.1493 + *    FLAC__stream_decoder_get_state().
 12.1494 + */
 12.1495 +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
 12.1496 +
 12.1497 +/** Skip one audio frame.
 12.1498 + *  This version instructs the decoder to 'skip' a single frame and stop,
 12.1499 + *  unless the callbacks return a fatal error or the read callback returns
 12.1500 + *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 12.1501 + *
 12.1502 + *  The decoding flow is the same as what occurs when
 12.1503 + *  FLAC__stream_decoder_process_single() is called to process an audio
 12.1504 + *  frame, except that this function does not decode the parsed data into
 12.1505 + *  PCM or call the write callback.  The integrity of the frame is still
 12.1506 + *  checked the same way as in the other process functions.
 12.1507 + *
 12.1508 + *  This function will return once one whole frame is skipped, in the
 12.1509 + *  same way that FLAC__stream_decoder_process_single() will return once
 12.1510 + *  one whole frame is decoded.
 12.1511 + *
 12.1512 + *  This function can be used in more quickly determining FLAC frame
 12.1513 + *  boundaries when decoding of the actual data is not needed, for
 12.1514 + *  example when an application is separating a FLAC stream into frames
 12.1515 + *  for editing or storing in a container.  To do this, the application
 12.1516 + *  can use FLAC__stream_decoder_skip_single_frame() to quickly advance
 12.1517 + *  to the next frame, then use
 12.1518 + *  FLAC__stream_decoder_get_decode_position() to find the new frame
 12.1519 + *  boundary.
 12.1520 + *
 12.1521 + *  This function should only be called when the stream has advanced
 12.1522 + *  past all the metadata, otherwise it will return \c false.
 12.1523 + *
 12.1524 + * \param  decoder  An initialized decoder instance not in a metadata
 12.1525 + *                  state.
 12.1526 + * \assert
 12.1527 + *    \code decoder != NULL \endcode
 12.1528 + * \retval FLAC__bool
 12.1529 + *    \c false if any fatal read, write, or memory allocation error
 12.1530 + *    occurred (meaning decoding must stop), or if the decoder
 12.1531 + *    is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
 12.1532 + *    FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
 12.1533 + *    information about the decoder, check the decoder state with
 12.1534 + *    FLAC__stream_decoder_get_state().
 12.1535 + */
 12.1536 +FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
 12.1537 +
 12.1538 +/** Flush the input and seek to an absolute sample.
 12.1539 + *  Decoding will resume at the given sample.  Note that because of
 12.1540 + *  this, the next write callback may contain a partial block.  The
 12.1541 + *  client must support seeking the input or this function will fail
 12.1542 + *  and return \c false.  Furthermore, if the decoder state is
 12.1543 + *  \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
 12.1544 + *  with FLAC__stream_decoder_flush() or reset with
 12.1545 + *  FLAC__stream_decoder_reset() before decoding can continue.
 12.1546 + *
 12.1547 + * \param  decoder  A decoder instance.
 12.1548 + * \param  sample   The target sample number to seek to.
 12.1549 + * \assert
 12.1550 + *    \code decoder != NULL \endcode
 12.1551 + * \retval FLAC__bool
 12.1552 + *    \c true if successful, else \c false.
 12.1553 + */
 12.1554 +FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
 12.1555 +
 12.1556 +/* \} */
 12.1557 +
 12.1558 +#ifdef __cplusplus
 12.1559 +}
 12.1560 +#endif
 12.1561 +
 12.1562 +#endif
    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/VisualC/flac/include/FLAC/stream_encoder.h	Sun Jan 01 14:40:22 2012 -0500
    13.3 @@ -0,0 +1,1768 @@
    13.4 +/* libFLAC - Free Lossless Audio Codec library
    13.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
    13.6 + *
    13.7 + * Redistribution and use in source and binary forms, with or without
    13.8 + * modification, are permitted provided that the following conditions
    13.9 + * are met:
   13.10 + *
   13.11 + * - Redistributions of source code must retain the above copyright
   13.12 + * notice, this list of conditions and the following disclaimer.
   13.13 + *
   13.14 + * - Redistributions in binary form must reproduce the above copyright
   13.15 + * notice, this list of conditions and the following disclaimer in the
   13.16 + * documentation and/or other materials provided with the distribution.
   13.17 + *
   13.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
   13.19 + * contributors may be used to endorse or promote products derived from
   13.20 + * this software without specific prior written permission.
   13.21 + *
   13.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   13.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   13.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   13.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
   13.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   13.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   13.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   13.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   13.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   13.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   13.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   13.33 + */
   13.34 +
   13.35 +#ifndef FLAC__STREAM_ENCODER_H
   13.36 +#define FLAC__STREAM_ENCODER_H
   13.37 +
   13.38 +#include <stdio.h> /* for FILE */
   13.39 +#include "export.h"
   13.40 +#include "format.h"
   13.41 +#include "stream_decoder.h"
   13.42 +
   13.43 +#ifdef __cplusplus
   13.44 +extern "C" {
   13.45 +#endif
   13.46 +
   13.47 +
   13.48 +/** \file include/FLAC/stream_encoder.h
   13.49 + *
   13.50 + *  \brief
   13.51 + *  This module contains the functions which implement the stream
   13.52 + *  encoder.
   13.53 + *
   13.54 + *  See the detailed documentation in the
   13.55 + *  \link flac_stream_encoder stream encoder \endlink module.
   13.56 + */
   13.57 +
   13.58 +/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
   13.59 + *  \ingroup flac
   13.60 + *
   13.61 + *  \brief
   13.62 + *  This module describes the encoder layers provided by libFLAC.
   13.63 + *
   13.64 + * The stream encoder can be used to encode complete streams either to the
   13.65 + * client via callbacks, or directly to a file, depending on how it is
   13.66 + * initialized.  When encoding via callbacks, the client provides a write
   13.67 + * callback which will be called whenever FLAC data is ready to be written.
   13.68 + * If the client also supplies a seek callback, the encoder will also
   13.69 + * automatically handle the writing back of metadata discovered while
   13.70 + * encoding, like stream info, seek points offsets, etc.  When encoding to
   13.71 + * a file, the client needs only supply a filename or open \c FILE* and an
   13.72 + * optional progress callback for periodic notification of progress; the
   13.73 + * write and seek callbacks are supplied internally.  For more info see the
   13.74 + * \link flac_stream_encoder stream encoder \endlink module.
   13.75 + */
   13.76 +
   13.77 +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
   13.78 + *  \ingroup flac_encoder
   13.79 + *
   13.80 + *  \brief
   13.81 + *  This module contains the functions which implement the stream
   13.82 + *  encoder.
   13.83 + *
   13.84 + * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
   13.85 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
   13.86 + *
   13.87 + * The basic usage of this encoder is as follows:
   13.88 + * - The program creates an instance of an encoder using
   13.89 + *   FLAC__stream_encoder_new().
   13.90 + * - The program overrides the default settings using
   13.91 + *   FLAC__stream_encoder_set_*() functions.  At a minimum, the following
   13.92 + *   functions should be called:
   13.93 + *   - FLAC__stream_encoder_set_channels()
   13.94 + *   - FLAC__stream_encoder_set_bits_per_sample()
   13.95 + *   - FLAC__stream_encoder_set_sample_rate()
   13.96 + *   - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
   13.97 + *   - FLAC__stream_encoder_set_total_samples_estimate() (if known)
   13.98 + * - If the application wants to control the compression level or set its own
   13.99 + *   metadata, then the following should also be called:
  13.100 + *   - FLAC__stream_encoder_set_compression_level()
  13.101 + *   - FLAC__stream_encoder_set_verify()
  13.102 + *   - FLAC__stream_encoder_set_metadata()
  13.103 + * - The rest of the set functions should only be called if the client needs
  13.104 + *   exact control over how the audio is compressed; thorough understanding
  13.105 + *   of the FLAC format is necessary to achieve good results.
  13.106 + * - The program initializes the instance to validate the settings and
  13.107 + *   prepare for encoding using
  13.108 + *   - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
  13.109 + *     or FLAC__stream_encoder_init_file() for native FLAC
  13.110 + *   - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
  13.111 + *     or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
  13.112 + * - The program calls FLAC__stream_encoder_process() or
  13.113 + *   FLAC__stream_encoder_process_interleaved() to encode data, which
  13.114 + *   subsequently calls the callbacks when there is encoder data ready
  13.115 + *   to be written.
  13.116 + * - The program finishes the encoding with FLAC__stream_encoder_finish(),
  13.117 + *   which causes the encoder to encode any data still in its input pipe,
  13.118 + *   update the metadata with the final encoding statistics if output
  13.119 + *   seeking is possible, and finally reset the encoder to the
  13.120 + *   uninitialized state.
  13.121 + * - The instance may be used again or deleted with
  13.122 + *   FLAC__stream_encoder_delete().
  13.123 + *
  13.124 + * In more detail, the stream encoder functions similarly to the
  13.125 + * \link flac_stream_decoder stream decoder \endlink, but has fewer
  13.126 + * callbacks and more options.  Typically the client will create a new
  13.127 + * instance by calling FLAC__stream_encoder_new(), then set the necessary
  13.128 + * parameters with FLAC__stream_encoder_set_*(), and initialize it by
  13.129 + * calling one of the FLAC__stream_encoder_init_*() functions.
  13.130 + *
  13.131 + * Unlike the decoders, the stream encoder has many options that can
  13.132 + * affect the speed and compression ratio.  When setting these parameters
  13.133 + * you should have some basic knowledge of the format (see the
  13.134 + * <A HREF="../documentation.html#format">user-level documentation</A>
  13.135 + * or the <A HREF="../format.html">formal description</A>).  The
  13.136 + * FLAC__stream_encoder_set_*() functions themselves do not validate the
  13.137 + * values as many are interdependent.  The FLAC__stream_encoder_init_*()
  13.138 + * functions will do this, so make sure to pay attention to the state
  13.139 + * returned by FLAC__stream_encoder_init_*() to make sure that it is
  13.140 + * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
  13.141 + * before FLAC__stream_encoder_init_*() will take on the defaults from
  13.142 + * the constructor.
  13.143 + *
  13.144 + * There are three initialization functions for native FLAC, one for
  13.145 + * setting up the encoder to encode FLAC data to the client via
  13.146 + * callbacks, and two for encoding directly to a file.
  13.147 + *
  13.148 + * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
  13.149 + * You must also supply a write callback which will be called anytime
  13.150 + * there is raw encoded data to write.  If the client can seek the output
  13.151 + * it is best to also supply seek and tell callbacks, as this allows the
  13.152 + * encoder to go back after encoding is finished to write back
  13.153 + * information that was collected while encoding, like seek point offsets,
  13.154 + * frame sizes, etc.
  13.155 + *
  13.156 + * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
  13.157 + * or FLAC__stream_encoder_init_file().  Then you must only supply a
  13.158 + * filename or open \c FILE*; the encoder will handle all the callbacks
  13.159 + * internally.  You may also supply a progress callback for periodic
  13.160 + * notification of the encoding progress.
  13.161 + *
  13.162 + * There are three similarly-named init functions for encoding to Ogg
  13.163 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  13.164 + * library has been built with Ogg support.
  13.165 + *
  13.166 + * The call to FLAC__stream_encoder_init_*() currently will also immediately
  13.167 + * call the write callback several times, once with the \c fLaC signature,
  13.168 + * and once for each encoded metadata block.  Note that for Ogg FLAC
  13.169 + * encoding you will usually get at least twice the number of callbacks than
  13.170 + * with native FLAC, one for the Ogg page header and one for the page body.
  13.171 + *
  13.172 + * After initializing the instance, the client may feed audio data to the
  13.173 + * encoder in one of two ways:
  13.174 + *
  13.175 + * - Channel separate, through FLAC__stream_encoder_process() - The client
  13.176 + *   will pass an array of pointers to buffers, one for each channel, to
  13.177 + *   the encoder, each of the same length.  The samples need not be
  13.178 + *   block-aligned, but each channel should have the same number of samples.
  13.179 + * - Channel interleaved, through
  13.180 + *   FLAC__stream_encoder_process_interleaved() - The client will pass a single
  13.181 + *   pointer to data that is channel-interleaved (i.e. channel0_sample0,
  13.182 + *   channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  13.183 + *   Again, the samples need not be block-aligned but they must be
  13.184 + *   sample-aligned, i.e. the first value should be channel0_sample0 and
  13.185 + *   the last value channelN_sampleM.
  13.186 + *
  13.187 + * Note that for either process call, each sample in the buffers should be a
  13.188 + * signed integer, right-justified to the resolution set by
  13.189 + * FLAC__stream_encoder_set_bits_per_sample().  For example, if the resolution
  13.190 + * is 16 bits per sample, the samples should all be in the range [-32768,32767].
  13.191 + *
  13.192 + * When the client is finished encoding data, it calls
  13.193 + * FLAC__stream_encoder_finish(), which causes the encoder to encode any
  13.194 + * data still in its input pipe, and call the metadata callback with the
  13.195 + * final encoding statistics.  Then the instance may be deleted with
  13.196 + * FLAC__stream_encoder_delete() or initialized again to encode another
  13.197 + * stream.
  13.198 + *
  13.199 + * For programs that write their own metadata, but that do not know the
  13.200 + * actual metadata until after encoding, it is advantageous to instruct
  13.201 + * the encoder to write a PADDING block of the correct size, so that
  13.202 + * instead of rewriting the whole stream after encoding, the program can
  13.203 + * just overwrite the PADDING block.  If only the maximum size of the
  13.204 + * metadata is known, the program can write a slightly larger padding
  13.205 + * block, then split it after encoding.
  13.206 + *
  13.207 + * Make sure you understand how lengths are calculated.  All FLAC metadata
  13.208 + * blocks have a 4 byte header which contains the type and length.  This
  13.209 + * length does not include the 4 bytes of the header.  See the format page
  13.210 + * for the specification of metadata blocks and their lengths.
  13.211 + *
  13.212 + * \note
  13.213 + * If you are writing the FLAC data to a file via callbacks, make sure it
  13.214 + * is open for update (e.g. mode "w+" for stdio streams).  This is because
  13.215 + * after the first encoding pass, the encoder will try to seek back to the
  13.216 + * beginning of the stream, to the STREAMINFO block, to write some data
  13.217 + * there.  (If using FLAC__stream_encoder_init*_file() or
  13.218 + * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
  13.219 + *
  13.220 + * \note
  13.221 + * The "set" functions may only be called when the encoder is in the
  13.222 + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
  13.223 + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
  13.224 + * before FLAC__stream_encoder_init_*().  If this is the case they will
  13.225 + * return \c true, otherwise \c false.
  13.226 + *
  13.227 + * \note
  13.228 + * FLAC__stream_encoder_finish() resets all settings to the constructor
  13.229 + * defaults.
  13.230 + *
  13.231 + * \{
  13.232 + */
  13.233 +
  13.234 +
  13.235 +/** State values for a FLAC__StreamEncoder.
  13.236 + *
  13.237 + * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
  13.238 + *
  13.239 + * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
  13.240 + * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
  13.241 + * must be deleted with FLAC__stream_encoder_delete().
  13.242 + */
  13.243 +typedef enum {
  13.244 +
  13.245 +	FLAC__STREAM_ENCODER_OK = 0,
  13.246 +	/**< The encoder is in the normal OK state and samples can be processed. */
  13.247 +
  13.248 +	FLAC__STREAM_ENCODER_UNINITIALIZED,
  13.249 +	/**< The encoder is in the uninitialized state; one of the
  13.250 +	 * FLAC__stream_encoder_init_*() functions must be called before samples
  13.251 +	 * can be processed.
  13.252 +	 */
  13.253 +
  13.254 +	FLAC__STREAM_ENCODER_OGG_ERROR,
  13.255 +	/**< An error occurred in the underlying Ogg layer.  */
  13.256 +
  13.257 +	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
  13.258 +	/**< An error occurred in the underlying verify stream decoder;
  13.259 +	 * check FLAC__stream_encoder_get_verify_decoder_state().
  13.260 +	 */
  13.261 +
  13.262 +	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
  13.263 +	/**< The verify decoder detected a mismatch between the original
  13.264 +	 * audio signal and the decoded audio signal.
  13.265 +	 */
  13.266 +
  13.267 +	FLAC__STREAM_ENCODER_CLIENT_ERROR,
  13.268 +	/**< One of the callbacks returned a fatal error. */
  13.269 +
  13.270 +	FLAC__STREAM_ENCODER_IO_ERROR,
  13.271 +	/**< An I/O error occurred while opening/reading/writing a file.
  13.272 +	 * Check \c errno.
  13.273 +	 */
  13.274 +
  13.275 +	FLAC__STREAM_ENCODER_FRAMING_ERROR,
  13.276 +	/**< An error occurred while writing the stream; usually, the
  13.277 +	 * write_callback returned an error.
  13.278 +	 */
  13.279 +
  13.280 +	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
  13.281 +	/**< Memory allocation failed. */
  13.282 +
  13.283 +} FLAC__StreamEncoderState;
  13.284 +
  13.285 +/** Maps a FLAC__StreamEncoderState to a C string.
  13.286 + *
  13.287 + *  Using a FLAC__StreamEncoderState as the index to this array
  13.288 + *  will give the string equivalent.  The contents should not be modified.
  13.289 + */
  13.290 +extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
  13.291 +
  13.292 +
  13.293 +/** Possible return values for the FLAC__stream_encoder_init_*() functions.
  13.294 + */
  13.295 +typedef enum {
  13.296 +
  13.297 +	FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
  13.298 +	/**< Initialization was successful. */
  13.299 +
  13.300 +	FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
  13.301 +	/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
  13.302 +
  13.303 +	FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  13.304 +	/**< The library was not compiled with support for the given container
  13.305 +	 * format.
  13.306 +	 */
  13.307 +
  13.308 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
  13.309 +	/**< A required callback was not supplied. */
  13.310 +
  13.311 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
  13.312 +	/**< The encoder has an invalid setting for number of channels. */
  13.313 +
  13.314 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
  13.315 +	/**< The encoder has an invalid setting for bits-per-sample.
  13.316 +	 * FLAC supports 4-32 bps but the reference encoder currently supports
  13.317 +	 * only up to 24 bps.
  13.318 +	 */
  13.319 +
  13.320 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
  13.321 +	/**< The encoder has an invalid setting for the input sample rate. */
  13.322 +
  13.323 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
  13.324 +	/**< The encoder has an invalid setting for the block size. */
  13.325 +
  13.326 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
  13.327 +	/**< The encoder has an invalid setting for the maximum LPC order. */
  13.328 +
  13.329 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
  13.330 +	/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
  13.331 +
  13.332 +	FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
  13.333 +	/**< The specified block size is less than the maximum LPC order. */
  13.334 +
  13.335 +	FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
  13.336 +	/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
  13.337 +
  13.338 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
  13.339 +	/**< The metadata input to the encoder is invalid, in one of the following ways:
  13.340 +	 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
  13.341 +	 * - One of the metadata blocks contains an undefined type
  13.342 +	 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
  13.343 +	 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
  13.344 +	 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
  13.345 +	 */
  13.346 +
  13.347 +	FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
  13.348 +	/**< FLAC__stream_encoder_init_*() was called when the encoder was
  13.349 +	 * already initialized, usually because
  13.350 +	 * FLAC__stream_encoder_finish() was not called.
  13.351 +	 */
  13.352 +
  13.353 +} FLAC__StreamEncoderInitStatus;
  13.354 +
  13.355 +/** Maps a FLAC__StreamEncoderInitStatus to a C string.
  13.356 + *
  13.357 + *  Using a FLAC__StreamEncoderInitStatus as the index to this array
  13.358 + *  will give the string equivalent.  The contents should not be modified.
  13.359 + */
  13.360 +extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
  13.361 +
  13.362 +
  13.363 +/** Return values for the FLAC__StreamEncoder read callback.
  13.364 + */
  13.365 +typedef enum {
  13.366 +
  13.367 +	FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
  13.368 +	/**< The read was OK and decoding can continue. */
  13.369 +
  13.370 +	FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
  13.371 +	/**< The read was attempted at the end of the stream. */
  13.372 +
  13.373 +	FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
  13.374 +	/**< An unrecoverable error occurred. */
  13.375 +
  13.376 +	FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
  13.377 +	/**< Client does not support reading back from the output. */
  13.378 +
  13.379 +} FLAC__StreamEncoderReadStatus;
  13.380 +
  13.381 +/** Maps a FLAC__StreamEncoderReadStatus to a C string.
  13.382 + *
  13.383 + *  Using a FLAC__StreamEncoderReadStatus as the index to this array
  13.384 + *  will give the string equivalent.  The contents should not be modified.
  13.385 + */
  13.386 +extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
  13.387 +
  13.388 +
  13.389 +/** Return values for the FLAC__StreamEncoder write callback.
  13.390 + */
  13.391 +typedef enum {
  13.392 +
  13.393 +	FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
  13.394 +	/**< The write was OK and encoding can continue. */
  13.395 +
  13.396 +	FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
  13.397 +	/**< An unrecoverable error occurred.  The encoder will return from the process call. */
  13.398 +
  13.399 +} FLAC__StreamEncoderWriteStatus;
  13.400 +
  13.401 +/** Maps a FLAC__StreamEncoderWriteStatus to a C string.
  13.402 + *
  13.403 + *  Using a FLAC__StreamEncoderWriteStatus as the index to this array
  13.404 + *  will give the string equivalent.  The contents should not be modified.
  13.405 + */
  13.406 +extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
  13.407 +
  13.408 +
  13.409 +/** Return values for the FLAC__StreamEncoder seek callback.
  13.410 + */
  13.411 +typedef enum {
  13.412 +
  13.413 +	FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
  13.414 +	/**< The seek was OK and encoding can continue. */
  13.415 +
  13.416 +	FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
  13.417 +	/**< An unrecoverable error occurred. */
  13.418 +
  13.419 +	FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  13.420 +	/**< Client does not support seeking. */
  13.421 +
  13.422 +} FLAC__StreamEncoderSeekStatus;
  13.423 +
  13.424 +/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
  13.425 + *
  13.426 + *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
  13.427 + *  will give the string equivalent.  The contents should not be modified.
  13.428 + */
  13.429 +extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
  13.430 +
  13.431 +
  13.432 +/** Return values for the FLAC__StreamEncoder tell callback.
  13.433 + */
  13.434 +typedef enum {
  13.435 +
  13.436 +	FLAC__STREAM_ENCODER_TELL_STATUS_OK,
  13.437 +	/**< The tell was OK and encoding can continue. */
  13.438 +
  13.439 +	FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
  13.440 +	/**< An unrecoverable error occurred. */
  13.441 +
  13.442 +	FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  13.443 +	/**< Client does not support seeking. */
  13.444 +
  13.445 +} FLAC__StreamEncoderTellStatus;
  13.446 +
  13.447 +/** Maps a FLAC__StreamEncoderTellStatus to a C string.
  13.448 + *
  13.449 + *  Using a FLAC__StreamEncoderTellStatus as the index to this array
  13.450 + *  will give the string equivalent.  The contents should not be modified.
  13.451 + */
  13.452 +extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
  13.453 +
  13.454 +
  13.455 +/***********************************************************************
  13.456 + *
  13.457 + * class FLAC__StreamEncoder
  13.458 + *
  13.459 + ***********************************************************************/
  13.460 +
  13.461 +struct FLAC__StreamEncoderProtected;
  13.462 +struct FLAC__StreamEncoderPrivate;
  13.463 +/** The opaque structure definition for the stream encoder type.
  13.464 + *  See the \link flac_stream_encoder stream encoder module \endlink
  13.465 + *  for a detailed description.
  13.466 + */
  13.467 +typedef struct {
  13.468 +	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  13.469 +	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
  13.470 +} FLAC__StreamEncoder;
  13.471 +
  13.472 +/** Signature for the read callback.
  13.473 + *
  13.474 + *  A function pointer matching this signature must be passed to
  13.475 + *  FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
  13.476 + *  The supplied function will be called when the encoder needs to read back
  13.477 + *  encoded data.  This happens during the metadata callback, when the encoder
  13.478 + *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
  13.479 + *  while encoding.  The address of the buffer to be filled is supplied, along
  13.480 + *  with the number of bytes the buffer can hold.  The callback may choose to
  13.481 + *  supply less data and modify the byte count but must be careful not to
  13.482 + *  overflow the buffer.  The callback then returns a status code chosen from
  13.483 + *  FLAC__StreamEncoderReadStatus.
  13.484 + *
  13.485 + * Here is an example of a read callback for stdio streams:
  13.486 + * \code
  13.487 + * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  13.488 + * {
  13.489 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.490 + *   if(*bytes > 0) {
  13.491 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  13.492 + *     if(ferror(file))
  13.493 + *       return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  13.494 + *     else if(*bytes == 0)
  13.495 + *       return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
  13.496 + *     else
  13.497 + *       return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
  13.498 + *   }
  13.499 + *   else
  13.500 + *     return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  13.501 + * }
  13.502 + * \endcode
  13.503 + *
  13.504 + * \note In general, FLAC__StreamEncoder functions which change the
  13.505 + * state should not be called on the \a encoder while in the callback.
  13.506 + *
  13.507 + * \param  encoder  The encoder instance calling the callback.
  13.508 + * \param  buffer   A pointer to a location for the callee to store
  13.509 + *                  data to be encoded.
  13.510 + * \param  bytes    A pointer to the size of the buffer.  On entry
  13.511 + *                  to the callback, it contains the maximum number
  13.512 + *                  of bytes that may be stored in \a buffer.  The
  13.513 + *                  callee must set it to the actual number of bytes
  13.514 + *                  stored (0 in case of error or end-of-stream) before
  13.515 + *                  returning.
  13.516 + * \param  client_data  The callee's client data set through
  13.517 + *                      FLAC__stream_encoder_set_client_data().
  13.518 + * \retval FLAC__StreamEncoderReadStatus
  13.519 + *    The callee's return status.
  13.520 + */
  13.521 +typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  13.522 +
  13.523 +/** Signature for the write callback.
  13.524 + *
  13.525 + *  A function pointer matching this signature must be passed to
  13.526 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  13.527 + *  by the encoder anytime there is raw encoded data ready to write.  It may
  13.528 + *  include metadata mixed with encoded audio frames and the data is not
  13.529 + *  guaranteed to be aligned on frame or metadata block boundaries.
  13.530 + *
  13.531 + *  The only duty of the callback is to write out the \a bytes worth of data
  13.532 + *  in \a buffer to the current position in the output stream.  The arguments
  13.533 + *  \a samples and \a current_frame are purely informational.  If \a samples
  13.534 + *  is greater than \c 0, then \a current_frame will hold the current frame
  13.535 + *  number that is being written; otherwise it indicates that the write
  13.536 + *  callback is being called to write metadata.
  13.537 + *
  13.538 + * \note
  13.539 + * Unlike when writing to native FLAC, when writing to Ogg FLAC the
  13.540 + * write callback will be called twice when writing each audio
  13.541 + * frame; once for the page header, and once for the page body.
  13.542 + * When writing the page header, the \a samples argument to the
  13.543 + * write callback will be \c 0.
  13.544 + *
  13.545 + * \note In general, FLAC__StreamEncoder functions which change the
  13.546 + * state should not be called on the \a encoder while in the callback.
  13.547 + *
  13.548 + * \param  encoder  The encoder instance calling the callback.
  13.549 + * \param  buffer   An array of encoded data of length \a bytes.
  13.550 + * \param  bytes    The byte length of \a buffer.
  13.551 + * \param  samples  The number of samples encoded by \a buffer.
  13.552 + *                  \c 0 has a special meaning; see above.
  13.553 + * \param  current_frame  The number of the current frame being encoded.
  13.554 + * \param  client_data  The callee's client data set through
  13.555 + *                      FLAC__stream_encoder_init_*().
  13.556 + * \retval FLAC__StreamEncoderWriteStatus
  13.557 + *    The callee's return status.
  13.558 + */
  13.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);
  13.560 +
  13.561 +/** Signature for the seek callback.
  13.562 + *
  13.563 + *  A function pointer matching this signature may be passed to
  13.564 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  13.565 + *  when the encoder needs to seek the output stream.  The encoder will pass
  13.566 + *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
  13.567 + *
  13.568 + * Here is an example of a seek callback for stdio streams:
  13.569 + * \code
  13.570 + * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  13.571 + * {
  13.572 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.573 + *   if(file == stdin)
  13.574 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
  13.575 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  13.576 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
  13.577 + *   else
  13.578 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
  13.579 + * }
  13.580 + * \endcode
  13.581 + *
  13.582 + * \note In general, FLAC__StreamEncoder functions which change the
  13.583 + * state should not be called on the \a encoder while in the callback.
  13.584 + *
  13.585 + * \param  encoder  The encoder instance calling the callback.
  13.586 + * \param  absolute_byte_offset  The offset from the beginning of the stream
  13.587 + *                               to seek to.
  13.588 + * \param  client_data  The callee's client data set through
  13.589 + *                      FLAC__stream_encoder_init_*().
  13.590 + * \retval FLAC__StreamEncoderSeekStatus
  13.591 + *    The callee's return status.
  13.592 + */
  13.593 +typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  13.594 +
  13.595 +/** Signature for the tell callback.
  13.596 + *
  13.597 + *  A function pointer matching this signature may be passed to
  13.598 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  13.599 + *  when the encoder needs to know the current position of the output stream.
  13.600 + *
  13.601 + * \warning
  13.602 + * The callback must return the true current byte offset of the output to
  13.603 + * which the encoder is writing.  If you are buffering the output, make
  13.604 + * sure and take this into account.  If you are writing directly to a
  13.605 + * FILE* from your write callback, ftell() is sufficient.  If you are
  13.606 + * writing directly to a file descriptor from your write callback, you
  13.607 + * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
  13.608 + * these points to rewrite metadata after encoding.
  13.609 + *
  13.610 + * Here is an example of a tell callback for stdio streams:
  13.611 + * \code
  13.612 + * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  13.613 + * {
  13.614 + *   FILE *file = ((MyClientData*)client_data)->file;
  13.615 + *   off_t pos;
  13.616 + *   if(file == stdin)
  13.617 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
  13.618 + *   else if((pos = ftello(file)) < 0)
  13.619 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
  13.620 + *   else {
  13.621 + *     *absolute_byte_offset = (FLAC__uint64)pos;
  13.622 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
  13.623 + *   }
  13.624 + * }
  13.625 + * \endcode
  13.626 + *
  13.627 + * \note In general, FLAC__StreamEncoder functions which change the
  13.628 + * state should not be called on the \a encoder while in the callback.
  13.629 + *
  13.630 + * \param  encoder  The encoder instance calling the callback.
  13.631 + * \param  absolute_byte_offset  The address at which to store the current
  13.632 + *                               position of the output.
  13.633 + * \param  client_data  The callee's client data set through
  13.634 + *                      FLAC__stream_encoder_init_*().
  13.635 + * \retval FLAC__StreamEncoderTellStatus
  13.636 + *    The callee's return status.
  13.637 + */
  13.638 +typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  13.639 +
  13.640 +/** Signature for the metadata callback.
  13.641 + *
  13.642 + *  A function pointer matching this signature may be passed to
  13.643 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
  13.644 + *  once at the end of encoding with the populated STREAMINFO structure.  This
  13.645 + *  is so the client can seek back to the beginning of the file and write the
  13.646 + *  STREAMINFO block with the correct statistics after encoding (like
  13.647 + *  minimum/maximum frame size and total samples).
  13.648 + *
  13.649 + * \note In general, FLAC__StreamEncoder functions which change the
  13.650 + * state should not be called on the \a encoder while in the callback.
  13.651 + *
  13.652 + * \param  encoder      The encoder instance calling the callback.
  13.653 + * \param  metadata     The final populated STREAMINFO block.
  13.654 + * \param  client_data  The callee's client data set through
  13.655 + *                      FLAC__stream_encoder_init_*().
  13.656 + */
  13.657 +typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
  13.658 +
  13.659 +/** Signature for the progress callback.
  13.660 + *
  13.661 + *  A function pointer matching this signature may be passed to
  13.662 + *  FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
  13.663 + *  The supplied function will be called when the encoder has finished
  13.664 + *  writing a frame.  The \c total_frames_estimate argument to the
  13.665 + *  callback will be based on the value from
  13.666 + *  FLAC__stream_encoder_set_total_samples_estimate().
  13.667 + *
  13.668 + * \note In general, FLAC__StreamEncoder functions which change the
  13.669 + * state should not be called on the \a encoder while in the callback.
  13.670 + *
  13.671 + * \param  encoder          The encoder instance calling the callback.
  13.672 + * \param  bytes_written    Bytes written so far.
  13.673 + * \param  samples_written  Samples written so far.
  13.674 + * \param  frames_written   Frames written so far.
  13.675 + * \param  total_frames_estimate  The estimate of the total number of
  13.676 + *                                frames to be written.
  13.677 + * \param  client_data      The callee's client data set through
  13.678 + *                          FLAC__stream_encoder_init_*().
  13.679 + */
  13.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);
  13.681 +
  13.682 +
  13.683 +/***********************************************************************
  13.684 + *
  13.685 + * Class constructor/destructor
  13.686 + *
  13.687 + ***********************************************************************/
  13.688 +
  13.689 +/** Create a new stream encoder instance.  The instance is created with
  13.690 + *  default settings; see the individual FLAC__stream_encoder_set_*()
  13.691 + *  functions for each setting's default.
  13.692 + *
  13.693 + * \retval FLAC__StreamEncoder*
  13.694 + *    \c NULL if there was an error allocating memory, else the new instance.
  13.695 + */
  13.696 +FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
  13.697 +
  13.698 +/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
  13.699 + *
  13.700 + * \param encoder  A pointer to an existing encoder.
  13.701 + * \assert
  13.702 + *    \code encoder != NULL \endcode
  13.703 + */
  13.704 +FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  13.705 +
  13.706 +
  13.707 +/***********************************************************************
  13.708 + *
  13.709 + * Public class method prototypes
  13.710 + *
  13.711 + ***********************************************************************/
  13.712 +
  13.713 +/** Set the serial number for the FLAC stream to use in the Ogg container.
  13.714 + *
  13.715 + * \note
  13.716 + * This does not need to be set for native FLAC encoding.
  13.717 + *
  13.718 + * \note
  13.719 + * It is recommended to set a serial number explicitly as the default of '0'
  13.720 + * may collide with other streams.
  13.721 + *
  13.722 + * \default \c 0
  13.723 + * \param  encoder        An encoder instance to set.
  13.724 + * \param  serial_number  See above.
  13.725 + * \assert
  13.726 + *    \code encoder != NULL \endcode
  13.727 + * \retval FLAC__bool
  13.728 + *    \c false if the encoder is already initialized, else \c true.
  13.729 + */
  13.730 +FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
  13.731 +
  13.732 +/** Set the "verify" flag.  If \c true, the encoder will verify it's own
  13.733 + *  encoded output by feeding it through an internal decoder and comparing
  13.734 + *  the original signal against the decoded signal.  If a mismatch occurs,
  13.735 + *  the process call will return \c false.  Note that this will slow the
  13.736 + *  encoding process by the extra time required for decoding and comparison.
  13.737 + *
  13.738 + * \default \c false
  13.739 + * \param  encoder  An encoder instance to set.
  13.740 + * \param  value    Flag value (see above).
  13.741 + * \assert
  13.742 + *    \code encoder != NULL \endcode
  13.743 + * \retval FLAC__bool
  13.744 + *    \c false if the encoder is already initialized, else \c true.
  13.745 + */
  13.746 +FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
  13.747 +
  13.748 +/** Set the <A HREF="../format.html#subset">Subset</A> flag.  If \c true,
  13.749 + *  the encoder will comply with the Subset and will check the
  13.750 + *  settings during FLAC__stream_encoder_init_*() to see if all settings
  13.751 + *  comply.  If \c false, the settings may take advantage of the full
  13.752 + *  range that the format allows.
  13.753 + *
  13.754 + *  Make sure you know what it entails before setting this to \c false.
  13.755 + *
  13.756 + * \default \c true
  13.757 + * \param  encoder  An encoder instance to set.
  13.758 + * \param  value    Flag value (see above).
  13.759 + * \assert
  13.760 + *    \code encoder != NULL \endcode
  13.761 + * \retval FLAC__bool
  13.762 + *    \c false if the encoder is already initialized, else \c true.
  13.763 + */
  13.764 +FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
  13.765 +
  13.766 +/** Set the number of channels to be encoded.
  13.767 + *
  13.768 + * \default \c 2
  13.769 + * \param  encoder  An encoder instance to set.
  13.770 + * \param  value    See above.
  13.771 + * \assert
  13.772 + *    \code encoder != NULL \endcode
  13.773 + * \retval FLAC__bool
  13.774 + *    \c false if the encoder is already initialized, else \c true.
  13.775 + */
  13.776 +FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
  13.777 +
  13.778 +/** Set the sample resolution of the input to be encoded.
  13.779 + *
  13.780 + * \warning
  13.781 + * Do not feed the encoder data that is wider than the value you
  13.782 + * set here or you will generate an invalid stream.
  13.783 + *
  13.784 + * \default \c 16
  13.785 + * \param  encoder  An encoder instance to set.
  13.786 + * \param  value    See above.
  13.787 + * \assert
  13.788 + *    \code encoder != NULL \endcode
  13.789 + * \retval FLAC__bool
  13.790 + *    \c false if the encoder is already initialized, else \c true.
  13.791 + */
  13.792 +FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
  13.793 +
  13.794 +/** Set the sample rate (in Hz) of the input to be encoded.
  13.795 + *
  13.796 + * \default \c 44100
  13.797 + * \param  encoder  An encoder instance to set.
  13.798 + * \param  value    See above.
  13.799 + * \assert
  13.800 + *    \code encoder != NULL \endcode
  13.801 + * \retval FLAC__bool
  13.802 + *    \c false if the encoder is already initialized, else \c true.
  13.803 + */
  13.804 +FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
  13.805 +
  13.806 +/** Set the compression level
  13.807 + *
  13.808 + * The compression level is roughly proportional to the amount of effort
  13.809 + * the encoder expends to compress the file.  A higher level usually
  13.810 + * means more computation but higher compression.  The default level is
  13.811 + * suitable for most applications.
  13.812 + *
  13.813 + * Currently the levels range from \c 0 (fastest, least compression) to
  13.814 + * \c 8 (slowest, most compression).  A value larger than \c 8 will be
  13.815 + * treated as \c 8.
  13.816 + *
  13.817 + * This function automatically calls the following other \c _set_
  13.818 + * functions with appropriate values, so the client does not need to
  13.819 + * unless it specifically wants to override them:
  13.820 + * - FLAC__stream_encoder_set_do_mid_side_stereo()
  13.821 + * - FLAC__stream_encoder_set_loose_mid_side_stereo()
  13.822 + * - FLAC__stream_encoder_set_apodization()
  13.823 + * - FLAC__stream_encoder_set_max_lpc_order()
  13.824 + * - FLAC__stream_encoder_set_qlp_coeff_precision()
  13.825 + * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
  13.826 + * - FLAC__stream_encoder_set_do_escape_coding()
  13.827 + * - FLAC__stream_encoder_set_do_exhaustive_model_search()
  13.828 + * - FLAC__stream_encoder_set_min_residual_partition_order()
  13.829 + * - FLAC__stream_encoder_set_max_residual_partition_order()
  13.830 + * - FLAC__stream_encoder_set_rice_parameter_search_dist()
  13.831 + *
  13.832 + * The actual values set for each level are:
  13.833 + * <table>
  13.834 + * <tr>
  13.835 + *  <td><b>level</b><td>
  13.836 + *  <td>do mid-side stereo<td>
  13.837 + *  <td>loose mid-side stereo<td>
  13.838 + *  <td>apodization<td>
  13.839 + *  <td>max lpc order<td>
  13.840 + *  <td>qlp coeff precision<td>
  13.841 + *  <td>qlp coeff prec search<td>
  13.842 + *  <td>escape coding<td>
  13.843 + *  <td>exhaustive model search<td>
  13.844 + *  <td>min residual partition order<td>
  13.845 + *  <td>max residual partition order<td>
  13.846 + *  <td>rice parameter search dist<td>
  13.847 + * </tr>
  13.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>
  13.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>
  13.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>
  13.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>
  13.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>
  13.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>
  13.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>
  13.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>
  13.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>
  13.857 + * </table>
  13.858 + *
  13.859 + * \default \c 5
  13.860 + * \param  encoder  An encoder instance to set.
  13.861 + * \param  value    See above.
  13.862 + * \assert
  13.863 + *    \code encoder != NULL \endcode
  13.864 + * \retval FLAC__bool
  13.865 + *    \c false if the encoder is already initialized, else \c true.
  13.866 + */
  13.867 +FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
  13.868 +
  13.869 +/** Set the blocksize to use while encoding.
  13.870 + *
  13.871 + * The number of samples to use per frame.  Use \c 0 to let the encoder
  13.872 + * estimate a blocksize; this is usually best.
  13.873 + *
  13.874 + * \default \c 0
  13.875 + * \param  encoder  An encoder instance to set.
  13.876 + * \param  value    See above.
  13.877 + * \assert
  13.878 + *    \code encoder != NULL \endcode
  13.879 + * \retval FLAC__bool
  13.880 + *    \c false if the encoder is already initialized, else \c true.
  13.881 + */
  13.882 +FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
  13.883 +
  13.884 +/** Set to \c true to enable mid-side encoding on stereo input.  The
  13.885 + *  number of channels must be 2 for this to have any effect.  Set to
  13.886 + *  \c false to use only independent channel coding.
  13.887 + *
  13.888 + * \default \c false
  13.889 + * \param  encoder  An encoder instance to set.
  13.890 + * \param  value    Flag value (see above).
  13.891 + * \assert
  13.892 + *    \code encoder != NULL \endcode
  13.893 + * \retval FLAC__bool
  13.894 + *    \c false if the encoder is already initialized, else \c true.
  13.895 + */
  13.896 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  13.897 +
  13.898 +/** Set to \c true to enable adaptive switching between mid-side and
  13.899 + *  left-right encoding on stereo input.  Set to \c false to use
  13.900 + *  exhaustive searching.  Setting this to \c true requires
  13.901 + *  FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
  13.902 + *  \c true in order to have any effect.
  13.903 + *
  13.904 + * \default \c false
  13.905 + * \param  encoder  An encoder instance to set.
  13.906 + * \param  value    Flag value (see above).
  13.907 + * \assert
  13.908 + *    \code encoder != NULL \endcode
  13.909 + * \retval FLAC__bool
  13.910 + *    \c false if the encoder is already initialized, else \c true.
  13.911 + */
  13.912 +FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  13.913 +
  13.914 +/** Sets the apodization function(s) the encoder will use when windowing
  13.915 + *  audio data for LPC analysis.
  13.916 + *
  13.917 + * The \a specification is a plain ASCII string which specifies exactly
  13.918 + * which functions to use.  There may be more than one (up to 32),
  13.919 + * separated by \c ';' characters.  Some functions take one or more
  13.920 + * comma-separated arguments in parentheses.
  13.921 + *
  13.922 + * The available functions are \c bartlett, \c bartlett_hann,
  13.923 + * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
  13.924 + * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
  13.925 + * \c rectangle, \c triangle, \c tukey(P), \c welch.
  13.926 + *
  13.927 + * For \c gauss(STDDEV), STDDEV specifies the standard deviation
  13.928 + * (0<STDDEV<=0.5).
  13.929 + *
  13.930 + * For \c tukey(P), P specifies the fraction of the window that is
  13.931 + * tapered (0<=P<=1).  P=0 corresponds to \c rectangle and P=1
  13.932 + * corresponds to \c hann.
  13.933 + *
  13.934 + * Example specifications are \c "blackman" or
  13.935 + * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
  13.936 + *
  13.937 + * Any function that is specified erroneously is silently dropped.  Up
  13.938 + * to 32 functions are kept, the rest are dropped.  If the specification
  13.939 + * is empty the encoder defaults to \c "tukey(0.5)".
  13.940 + *
  13.941 + * When more than one function is specified, then for every subframe the
  13.942 + * encoder will try each of them separately and choose the window that
  13.943 + * results in the smallest compressed subframe.
  13.944 + *
  13.945 + * Note that each function specified causes the encoder to occupy a
  13.946 + * floating point array in which to store the window.
  13.947 + *
  13.948 + * \default \c "tukey(0.5)"
  13.949 + * \param  encoder        An encoder instance to set.
  13.950 + * \param  specification  See above.
  13.951 + * \assert
  13.952 + *    \code encoder != NULL \endcode
  13.953 + *    \code specification != NULL \endcode
  13.954 + * \retval FLAC__bool
  13.955 + *    \c false if the encoder is already initialized, else \c true.
  13.956 + */
  13.957 +FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
  13.958 +
  13.959 +/** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
  13.960 + *
  13.961 + * \default \c 0
  13.962 + * \param  encoder  An encoder instance to set.
  13.963 + * \param  value    See above.
  13.964 + * \assert
  13.965 + *    \code encoder != NULL \endcode
  13.966 + * \retval FLAC__bool
  13.967 + *    \c false if the encoder is already initialized, else \c true.
  13.968 + */
  13.969 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
  13.970 +
  13.971 +/** Set the precision, in bits, of the quantized linear predictor
  13.972 + *  coefficients, or \c 0 to let the encoder select it based on the
  13.973 + *  blocksize.
  13.974 + *
  13.975 + * \note
  13.976 + * In the current implementation, qlp_coeff_precision + bits_per_sample must
  13.977 + * be less than 32.
  13.978 + *
  13.979 + * \default \c 0
  13.980 + * \param  encoder  An encoder instance to set.
  13.981 + * \param  value    See above.
  13.982 + * \assert
  13.983 + *    \code encoder != NULL \endcode
  13.984 + * \retval FLAC__bool
  13.985 + *    \c false if the encoder is already initialized, else \c true.
  13.986 + */
  13.987 +FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
  13.988 +
  13.989 +/** Set to \c false to use only the specified quantized linear predictor
  13.990 + *  coefficient precision, or \c true to search neighboring precision
  13.991 + *  values and use the best one.
  13.992 + *
  13.993 + * \default \c false
  13.994 + * \param  encoder  An encoder instance to set.
  13.995 + * \param  value    See above.
  13.996 + * \assert
  13.997 + *    \code encoder != NULL \endcode
  13.998 + * \retval FLAC__bool
  13.999 + *    \c false if the encoder is already initialized, else \c true.
 13.1000 + */
 13.1001 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
 13.1002 +
 13.1003 +/** Deprecated.  Setting this value has no effect.
 13.1004 + *
 13.1005 + * \default \c false
 13.1006 + * \param  encoder  An encoder instance to set.
 13.1007 + * \param  value    See above.
 13.1008 + * \assert
 13.1009 + *    \code encoder != NULL \endcode
 13.1010 + * \retval FLAC__bool
 13.1011 + *    \c false if the encoder is already initialized, else \c true.
 13.1012 + */
 13.1013 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
 13.1014 +
 13.1015 +/** Set to \c false to let the encoder estimate the best model order
 13.1016 + *  based on the residual signal energy, or \c true to force the
 13.1017 + *  encoder to evaluate all order models and select the best.
 13.1018 + *
 13.1019 + * \default \c false
 13.1020 + * \param  encoder  An encoder instance to set.
 13.1021 + * \param  value    See above.
 13.1022 + * \assert
 13.1023 + *    \code encoder != NULL \endcode
 13.1024 + * \retval FLAC__bool
 13.1025 + *    \c false if the encoder is already initialized, else \c true.
 13.1026 + */
 13.1027 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
 13.1028 +
 13.1029 +/** Set the minimum partition order to search when coding the residual.
 13.1030 + *  This is used in tandem with
 13.1031 + *  FLAC__stream_encoder_set_max_residual_partition_order().
 13.1032 + *
 13.1033 + *  The partition order determines the context size in the residual.
 13.1034 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
 13.1035 + *
 13.1036 + *  Set both min and max values to \c 0 to force a single context,
 13.1037 + *  whose Rice parameter is based on the residual signal variance.
 13.1038 + *  Otherwise, set a min and max order, and the encoder will search
 13.1039 + *  all orders, using the mean of each context for its Rice parameter,
 13.1040 + *  and use the best.
 13.1041 + *
 13.1042 + * \default \c 0
 13.1043 + * \param  encoder  An encoder instance to set.
 13.1044 + * \param  value    See above.
 13.1045 + * \assert
 13.1046 + *    \code encoder != NULL \endcode
 13.1047 + * \retval FLAC__bool
 13.1048 + *    \c false if the encoder is already initialized, else \c true.
 13.1049 + */
 13.1050 +FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
 13.1051 +
 13.1052 +/** Set the maximum partition order to search when coding the residual.
 13.1053 + *  This is used in tandem with
 13.1054 + *  FLAC__stream_encoder_set_min_residual_partition_order().
 13.1055 + *
 13.1056 + *  The partition order determines the context size in the residual.
 13.1057 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
 13.1058 + *
 13.1059 + *  Set both min and max values to \c 0 to force a single context,
 13.1060 + *  whose Rice parameter is based on the residual signal variance.
 13.1061 + *  Otherwise, set a min and max order, and the encoder will search
 13.1062 + *  all orders, using the mean of each context for its Rice parameter,
 13.1063 + *  and use the best.
 13.1064 + *
 13.1065 + * \default \c 0
 13.1066 + * \param  encoder  An encoder instance to set.
 13.1067 + * \param  value    See above.
 13.1068 + * \assert
 13.1069 + *    \code encoder != NULL \endcode
 13.1070 + * \retval FLAC__bool
 13.1071 + *    \c false if the encoder is already initialized, else \c true.
 13.1072 + */
 13.1073 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
 13.1074 +
 13.1075 +/** Deprecated.  Setting this value has no effect.
 13.1076 + *
 13.1077 + * \default \c 0
 13.1078 + * \param  encoder  An encoder instance to set.
 13.1079 + * \param  value    See above.
 13.1080 + * \assert
 13.1081 + *    \code encoder != NULL \endcode
 13.1082 + * \retval FLAC__bool
 13.1083 + *    \c false if the encoder is already initialized, else \c true.
 13.1084 + */
 13.1085 +FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
 13.1086 +
 13.1087 +/** Set an estimate of the total samples that will be encoded.
 13.1088 + *  This is merely an estimate and may be set to \c 0 if unknown.
 13.1089 + *  This value will be written to the STREAMINFO block before encoding,
 13.1090 + *  and can remove the need for the caller to rewrite the value later
 13.1091 + *  if the value is known before encoding.
 13.1092 + *
 13.1093 + * \default \c 0
 13.1094 + * \param  encoder  An encoder instance to set.
 13.1095 + * \param  value    See above.
 13.1096 + * \assert
 13.1097 + *    \code encoder != NULL \endcode
 13.1098 + * \retval FLAC__bool
 13.1099 + *    \c false if the encoder is already initialized, else \c true.
 13.1100 + */
 13.1101 +FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
 13.1102 +
 13.1103 +/** Set the metadata blocks to be emitted to the stream before encoding.
 13.1104 + *  A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
 13.1105 + *  array of pointers to metadata blocks.  The array is non-const since
 13.1106 + *  the encoder may need to change the \a is_last flag inside them, and
 13.1107 + *  in some cases update seek point offsets.  Otherwise, the encoder will
 13.1108 + *  not modify or free the blocks.  It is up to the caller to free the
 13.1109 + *  metadata blocks after encoding finishes.
 13.1110 + *
 13.1111 + * \note
 13.1112 + * The encoder stores only copies of the pointers in the \a metadata array;
 13.1113 + * the metadata blocks themselves must survive at least until after
 13.1114 + * FLAC__stream_encoder_finish() returns.  Do not free the blocks until then.
 13.1115 + *
 13.1116 + * \note
 13.1117 + * The STREAMINFO block is always written and no STREAMINFO block may
 13.1118 + * occur in the supplied array.
 13.1119 + *
 13.1120 + * \note
 13.1121 + * By default the encoder does not create a SEEKTABLE.  If one is supplied
 13.1122 + * in the \a metadata array, but the client has specified that it does not
 13.1123 + * support seeking, then the SEEKTABLE will be written verbatim.  However
 13.1124 + * by itself this is not very useful as the client will not know the stream
 13.1125 + * offsets for the seekpoints ahead of time.  In order to get a proper
 13.1126 + * seektable the client must support seeking.  See next note.
 13.1127 + *
 13.1128 + * \note
 13.1129 + * SEEKTABLE blocks are handled specially.  Since you will not know
 13.1130 + * the values for the seek point stream offsets, you should pass in
 13.1131 + * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
 13.1132 + * required sample numbers (or placeholder points), with \c 0 for the
 13.1133 + * \a frame_samples and \a stream_offset fields for each point.  If the
 13.1134 + * client has specified that it supports seeking by providing a seek
 13.1135 + * callback to FLAC__stream_encoder_init_stream() or both seek AND read
 13.1136 + * callback to FLAC__stream_encoder_init_ogg_stream() (or by using
 13.1137 + * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()),
 13.1138 + * then while it is encoding the encoder will fill the stream offsets in
 13.1139 + * for you and when encoding is finished, it will seek back and write the
 13.1140 + * real values into the SEEKTABLE block in the stream.  There are helper
 13.1141 + * routines for manipulating seektable template blocks; see metadata.h:
 13.1142 + * FLAC__metadata_object_seektable_template_*().  If the client does
 13.1143 + * not support seeking, the SEEKTABLE will have inaccurate offsets which
 13.1144 + * will slow down or remove the ability to seek in the FLAC stream.
 13.1145 + *
 13.1146 + * \note
 13.1147 + * The encoder instance \b will modify the first \c SEEKTABLE block
 13.1148 + * as it transforms the template to a valid seektable while encoding,
 13.1149 + * but it is still up to the caller to free all metadata blocks after
 13.1150 + * encoding.
 13.1151 + *
 13.1152 + * \note
 13.1153 + * A VORBIS_COMMENT block may be supplied.  The vendor string in it
 13.1154 + * will be ignored.  libFLAC will use it's own vendor string. libFLAC
 13.1155 + * will not modify the passed-in VORBIS_COMMENT's vendor string, it
 13.1156 + * will simply write it's own into the stream.  If no VORBIS_COMMENT
 13.1157 + * block is present in the \a metadata array, libFLAC will write an
 13.1158 + * empty one, containing only the vendor string.
 13.1159 + *
 13.1160 + * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
 13.1161 + * the second metadata block of the stream.  The encoder already supplies
 13.1162 + * the STREAMINFO block automatically.  If \a metadata does not contain a
 13.1163 + * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
 13.1164 + * \a metadata does contain a VORBIS_COMMENT block and it is not the
 13.1165 + * first, the init function will reorder \a metadata by moving the
 13.1166 + * VORBIS_COMMENT block to the front; the relative ordering of the other
 13.1167 + * blocks will remain as they were.
 13.1168 + *
 13.1169 + * \note The Ogg FLAC mapping limits the number of metadata blocks per
 13.1170 + * stream to \c 65535.  If \a num_blocks exceeds this the function will
 13.1171 + * return \c false.
 13.1172 + *
 13.1173 + * \default \c NULL, 0
 13.1174 + * \param  encoder     An encoder instance to set.
 13.1175 + * \param  metadata    See above.
 13.1176 + * \param  num_blocks  See above.
 13.1177 + * \assert
 13.1178 + *    \code encoder != NULL \endcode
 13.1179 + * \retval FLAC__bool
 13.1180 + *    \c false if the encoder is already initialized, else \c true.
 13.1181 + *    \c false if the encoder is already initialized, or if
 13.1182 + *    \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
 13.1183 + */
 13.1184 +FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 13.1185 +
 13.1186 +/** Get the current encoder state.
 13.1187 + *
 13.1188 + * \param  encoder  An encoder instance to query.
 13.1189 + * \assert
 13.1190 + *    \code encoder != NULL \endcode
 13.1191 + * \retval FLAC__StreamEncoderState
 13.1192 + *    The current encoder state.
 13.1193 + */
 13.1194 +FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
 13.1195 +
 13.1196 +/** Get the state of the verify stream decoder.
 13.1197 + *  Useful when the stream encoder state is
 13.1198 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 13.1199 + *
 13.1200 + * \param  encoder  An encoder instance to query.
 13.1201 + * \assert
 13.1202 + *    \code encoder != NULL \endcode
 13.1203 + * \retval FLAC__StreamDecoderState
 13.1204 + *    The verify stream decoder state.
 13.1205 + */
 13.1206 +FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
 13.1207 +
 13.1208 +/** Get the current encoder state as a C string.
 13.1209 + *  This version automatically resolves
 13.1210 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
 13.1211 + *  verify decoder's state.
 13.1212 + *
 13.1213 + * \param  encoder  A encoder instance to query.
 13.1214 + * \assert
 13.1215 + *    \code encoder != NULL \endcode
 13.1216 + * \retval const char *
 13.1217 + *    The encoder state as a C string.  Do not modify the contents.
 13.1218 + */
 13.1219 +FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
 13.1220 +
 13.1221 +/** Get relevant values about the nature of a verify decoder error.
 13.1222 + *  Useful when the stream encoder state is
 13.1223 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.  The arguments should
 13.1224 + *  be addresses in which the stats will be returned, or NULL if value
 13.1225 + *  is not desired.
 13.1226 + *
 13.1227 + * \param  encoder  An encoder instance to query.
 13.1228 + * \param  absolute_sample  The absolute sample number of the mismatch.
 13.1229 + * \param  frame_number  The number of the frame in which the mismatch occurred.
 13.1230 + * \param  channel       The channel in which the mismatch occurred.
 13.1231 + * \param  sample        The number of the sample (relative to the frame) in
 13.1232 + *                       which the mismatch occurred.
 13.1233 + * \param  expected      The expected value for the sample in question.
 13.1234 + * \param  got           The actual value returned by the decoder.
 13.1235 + * \assert
 13.1236 + *    \code encoder != NULL \endcode
 13.1237 + */
 13.1238 +FLAC_API void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 13.1239 +
 13.1240 +/** Get the "verify" flag.
 13.1241 + *
 13.1242 + * \param  encoder  An encoder instance to query.
 13.1243 + * \assert
 13.1244 + *    \code encoder != NULL \endcode
 13.1245 + * \retval FLAC__bool
 13.1246 + *    See FLAC__stream_encoder_set_verify().
 13.1247 + */
 13.1248 +FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
 13.1249 +
 13.1250 +/** Get the <A HREF="../format.html#subset>Subset</A> flag.
 13.1251 + *
 13.1252 + * \param  encoder  An encoder instance to query.
 13.1253 + * \assert
 13.1254 + *    \code encoder != NULL \endcode
 13.1255 + * \retval FLAC__bool
 13.1256 + *    See FLAC__stream_encoder_set_streamable_subset().
 13.1257 + */
 13.1258 +FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
 13.1259 +
 13.1260 +/** Get the number of input channels being processed.
 13.1261 + *
 13.1262 + * \param  encoder  An encoder instance to query.
 13.1263 + * \assert
 13.1264 + *    \code encoder != NULL \endcode
 13.1265 + * \retval unsigned
 13.1266 + *    See FLAC__stream_encoder_set_channels().
 13.1267 + */
 13.1268 +FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
 13.1269 +
 13.1270 +/** Get the input sample resolution setting.
 13.1271 + *
 13.1272 + * \param  encoder  An encoder instance to query.
 13.1273 + * \assert
 13.1274 + *    \code encoder != NULL \endcode
 13.1275 + * \retval unsigned
 13.1276 + *    See FLAC__stream_encoder_set_bits_per_sample().
 13.1277 + */
 13.1278 +FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
 13.1279 +
 13.1280 +/** Get the input sample rate setting.
 13.1281 + *
 13.1282 + * \param  encoder  An encoder instance to query.
 13.1283 + * \assert
 13.1284 + *    \code encoder != NULL \endcode
 13.1285 + * \retval unsigned
 13.1286 + *    See FLAC__stream_encoder_set_sample_rate().
 13.1287 + */
 13.1288 +FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
 13.1289 +
 13.1290 +/** Get the blocksize setting.
 13.1291 + *
 13.1292 + * \param  encoder  An encoder instance to query.
 13.1293 + * \assert
 13.1294 + *    \code encoder != NULL \endcode
 13.1295 + * \retval unsigned
 13.1296 + *    See FLAC__stream_encoder_set_blocksize().
 13.1297 + */
 13.1298 +FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
 13.1299 +
 13.1300 +/** Get the "mid/side stereo coding" flag.
 13.1301 + *
 13.1302 + * \param  encoder  An encoder instance to query.
 13.1303 + * \assert
 13.1304 + *    \code encoder != NULL \endcode
 13.1305 + * \retval FLAC__bool
 13.1306 + *    See FLAC__stream_encoder_get_do_mid_side_stereo().
 13.1307 + */
 13.1308 +FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
 13.1309 +
 13.1310 +/** Get the "adaptive mid/side switching" flag.
 13.1311 + *
 13.1312 + * \param  encoder  An encoder instance to query.
 13.1313 + * \assert
 13.1314 + *    \code encoder != NULL \endcode
 13.1315 + * \retval FLAC__bool
 13.1316 + *    See FLAC__stream_encoder_set_loose_mid_side_stereo().
 13.1317 + */
 13.1318 +FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
 13.1319 +
 13.1320 +/** Get the maximum LPC order setting.
 13.1321 + *
 13.1322 + * \param  encoder  An encoder instance to query.
 13.1323 + * \assert
 13.1324 + *    \code encoder != NULL \endcode