seal 0.1.0

data/mpg123/ports/MSVC++/2008clr/examples/scanclr/Program.cs

@@ -0,0 +1,79 @@
+/*
+	scanclr: Estimate length (sample count) of a mpeg file and compare to length from exact scan.
+
+	copyright 2009 by the mpg123 project - free software under the terms of the LGPL 2.1
+	see COPYING and AUTHORS files in distribution or http://mpg123.org
+
+    CLR example initially written by Malcolm Boczek
+    Based on scan.c example initially written by Thomas Orgis
+*/
+
+/* Note the lack of error checking here.
+   While it would be nicer to inform the user about troubles, libmpg123 is designed _not_ to bite you on operations with invalid handles , etc.
+  You just jet invalid results on invalid operations... */
+/* Ditto for mpg123clr (MB) */
+
+/*
+	1.9.0.0 24-Sep-09	Function names harmonized with libmpg123 (mb)
+*/
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+using mpg123clr;
+
+namespace scanclr
+{
+    class Program
+    {
+        static void Main(string[] args)
+        {
+            if (args.Length < 1)
+            {
+                Console.WriteLine("\nI will give you the estimated and exact sample lengths of MPEG audio files.\n");
+                Console.WriteLine("\nUsage: scanclr <mpeg audio file list>\n\n");
+                Console.WriteLine("Press any key to exit:");
+                while (Console.Read() == 0) ;
+
+                return;
+            }
+
+
+            mpg123clr.mpg.ErrorCode err;
+
+            err = mpg123.mpg123_init();
+
+            mpg123 mp = new mpg123();
+            err = mp.mpg123_new();
+
+            mp.mpg123_param(mpg123clr.mpg.parms.resync_limit, -1, 0);
+
+            foreach (string name in args)
+            {
+
+                err = mp.mpg123_open(name);
+
+                long a, b;
+
+                a = mp.mpg123_length();
+
+                mp.mpg123_scan();
+
+                b = mp.mpg123_length();
+
+                mp.mpg123_close();
+
+                Console.WriteLine(string.Format("File {0}: estimated {1} vs. scanned {2}", name, a, b));
+            }
+
+            Console.WriteLine("\nPress any key to exit:");
+            while (Console.Read() == 0) ;
+
+            mp.Dispose();
+
+            mpg123.mpg123_exit();
+        }
+    }
+}

data/mpg123/ports/MSVC++/2008clr/examples/scanclr/Properties/AssemblyInfo.cs

@@ -0,0 +1,36 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle("scanclr")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("scanclr")]
+[assembly: AssemblyCopyright("© mpg123 project 2009")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// Setting ComVisible to false makes the types in this assembly not visible 
+// to COM components.  If you need to access a type in this assembly from 
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible(false)]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid("a22ea83e-2dba-4835-b0d8-cca3f0bc73a8")]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Build and Revision Numbers 
+// by using the '*' as shown below:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]

data/mpg123/ports/MSVC++/2008clr/examples/scanclr/scanclr.csproj

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="3.5" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
+    <ProductVersion>9.0.30729</ProductVersion>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>{53664927-0A21-4056-A5D5-C6A1B4B1F839}</ProjectGuid>
+    <OutputType>Exe</OutputType>
+    <AppDesignerFolder>Properties</AppDesignerFolder>
+    <RootNamespace>scanclr</RootNamespace>
+    <AssemblyName>scanclr</AssemblyName>
+    <TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
+    <FileAlignment>512</FileAlignment>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+    <PlatformTarget>x86</PlatformTarget>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+    <PlatformTarget>x86</PlatformTarget>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="System" />
+    <Reference Include="System.Core">
+      <RequiredTargetFramework>3.5</RequiredTargetFramework>
+    </Reference>
+    <Reference Include="System.Xml.Linq">
+      <RequiredTargetFramework>3.5</RequiredTargetFramework>
+    </Reference>
+    <Reference Include="System.Data.DataSetExtensions">
+      <RequiredTargetFramework>3.5</RequiredTargetFramework>
+    </Reference>
+    <Reference Include="System.Data" />
+    <Reference Include="System.Xml" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="Program.cs" />
+    <Compile Include="Properties\AssemblyInfo.cs" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\mpg123clr\mpg123clr.vcproj">
+      <Project>{99E8B20E-9C29-46BC-B766-A50F237D88BF}</Project>
+      <Name>mpg123clr</Name>
+    </ProjectReference>
+  </ItemGroup>
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
+       Other similar extension points exist, see Microsoft.Common.targets.
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+  -->
+  <PropertyGroup>
+    <PostBuildEvent>if exist "$(SolutionDir)$(ConfigurationName)\libmpg123.dll" copy /y "$(SolutionDir)$(ConfigurationName)\libmpg123.dll" "$(TargetDir)"</PostBuildEvent>
+  </PropertyGroup>
+</Project>

data/mpg123/ports/MSVC++/2008clr/mpg123clr/AssemblyInfo.cpp

@@ -0,0 +1,76 @@
+/*
+	mpg123clr: MPEG Audio Decoder library Common Language Runtime version.
+
+	copyright 2009 by Malcolm Boczek - free software under the terms of the LGPL 2.1
+	mpg123clr.dll is a derivative work of libmpg123 - all original mpg123 licensing terms apply.
+
+	All rights to this work freely assigned to the mpg123 project.
+*/
+/*
+	libmpg123: MPEG Audio Decoder library
+
+	copyright 1995-2008 by the mpg123 project - free software under the terms of the LGPL 2.1
+	see COPYING and AUTHORS files in distribution or http://mpg123.org
+
+*/
+/*
+	1.8.1.0	04-Aug-09	Initial release.
+*/
+
+#include "stdafx.h"
+
+using namespace System::Reflection;
+using namespace System::Runtime::CompilerServices;
+
+//
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+//
+[assembly:AssemblyTitleAttribute("mpg123clr.dll")];
+[assembly:AssemblyDescriptionAttribute("mpg123clr Dynamic Link Library")];
+[assembly:AssemblyConfigurationAttribute("")];
+[assembly:AssemblyCompanyAttribute("mpg123 Project")];
+[assembly:AssemblyProductAttribute("mpg123clr.dll")];
+[assembly:AssemblyCopyrightAttribute("� 2009-2011 by the mpg123 project")];
+[assembly:AssemblyTrademarkAttribute("")];
+[assembly:AssemblyCultureAttribute("")];		
+
+//
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the value or you can default the Revision and Build Numbers 
+// by using the '*' as shown below:
+
+[assembly:AssemblyVersionAttribute("1.13.0.0")];
+
+//
+// In order to sign your assembly you must specify a key to use. Refer to the 
+// Microsoft .NET Framework documentation for more information on assembly signing.
+//
+// Use the attributes below to control which key is used for signing. 
+//
+// Notes: 
+//   (*) If no key is specified, the assembly is not signed.
+//   (*) KeyName refers to a key that has been installed in the Crypto Service
+//       Provider (CSP) on your machine. KeyFile refers to a file which contains
+//       a key.
+//   (*) If the KeyFile and the KeyName values are both specified, the 
+//       following processing occurs:
+//       (1) If the KeyName can be found in the CSP, that key is used.
+//       (2) If the KeyName does not exist and the KeyFile does exist, the key 
+//           in the KeyFile is installed into the CSP and used.
+//   (*) In order to create a KeyFile, you can use the sn.exe (Strong Name) utility.
+//        When specifying the KeyFile, the location of the KeyFile should be
+//        relative to the project directory.
+//   (*) Delay Signing is an advanced option - see the Microsoft .NET Framework
+//       documentation for more information on this.
+//
+[assembly:AssemblyDelaySignAttribute(false)];
+[assembly:AssemblyKeyFileAttribute("")];
+[assembly:AssemblyKeyNameAttribute("")];

data/mpg123/ports/MSVC++/2008clr/mpg123clr/ReadMe.txt

@@ -0,0 +1,165 @@
+========================================================================
+    DYNAMIC LINK LIBRARY : mpg123clr Project Overview
+========================================================================
+
+Project Installation:
+
+The project is part of a Visual Studio 2008 Solution.
+
+The Visual Studio solution file is 2008clr.sln located in a folder/directory named 2008clr.
+
+This folder/directory should be located in the mpg123/ports/MSVC++ folder to maintain file relationships
+with required mpg123 library files. i.e. at mpg123/ports/MSVC++/2008clr.
+
+The solution includes the following projects:
+
+	mpg123clr			The mpg123 CLR project. This creates the CLR compatible DLL file.
+	scanclr				Demonstration project for comparison with scan.c example.
+	feedseekclr			Demonstration project for comparison with feedseek.c example
+	replacereaderclr	Demonstration project, how to implement ReplaceReader in CLR (proof of concept)
+	libmpg123			For convenience, ensures that libmpg123.lib is available for linking
+
+=========================================================================
+Compiling:
+Configuration Manager:
+
+mpg123clr requires linking to a libmpg123 static library, this library must be compiled prior to
+compiling the clr projects. mpg123clr uses relative folder position during linking; therefore either:-
+
+	ensure that the 2008clr solution is correctly located within the ports\msvc++ folder, or
+	change the "linker->input->additional dependencies" to suit your installation configuration
+
+NOTE: x64 Active Solution Platform configurations are not supplied with this solution but have been tested.
+(Effectively all that is required is to change all "include" references to account for the "x64" output locations) 
+
+NOTE: The "unsafe" context of the ReplaceReaderClr project is only required to allow the use of callbacks. 
+mpg123clr is written to avoid the use of "unsafe" for the majority of normal operations.
+
+
+==========================================================================
+Using mpg123clr:
+
+Mpg123clr is a CLR ready dll. Simply add a reference to the mpg123clr.dll file in your application project.
+
+You may also add a "using" directive in your program files. C# e.g. using mpg123clr;
+
+The mpg123clr project is configured to create an additional Intellisense documentation file (mpg123clr.xml)
+to assist usage. If you manually relocate the .dll please also copy the .xml file to ensure correct Intellisense 
+operation.
+
+===========================================================================
+Common Errors:
+
+1)	Problem: "Unhandled Exception - file not found" error when the application is executed.
+	Cause: Incorrect libmpg123 library build / missing libmpg123.dll.
+	Solution: Copy libmpg123.dll to the application output folder - possibly in a Post-Build Event (see scanclr for
+		an example).
+	Explanation: mpg123clr requires static library libmpg123.lib and NOT dynamic library libmpg123.dll. 
+		If the libmpg123 library is built using an incorrect Project Context (such as Debug_Generic_Dll), mpg123clr 
+		will attempt to load the libmpg123.dll at runtime even though this file is not required. 
+	Alternatively: Use Configuration Manager and select a non-dll build context for the libmpg123 project.
+		(i.e. Debug_Generic not Debug_Generic_Dll)
+	 
+===========================================================================
+Developer Notes:
+
+ 1) Documentation <remarks> do not appear in CLR Intellisense environment (at time of writing). 
+    So deferred in favour of <para> within <summary>.
+ 2) During development "off_t" parameters conflicted with intellisense (although size_t worked just fine)
+	Since many CLR functions that refer to off_t features (e.g. positioners) actually expect 64bit long
+	(or long long in C++) parameters, I've implemented off_t as a long long - with one notable exception. 
+	This fixed intellisense and accommodates the CLR 64bit long implementation positioners: And then intellisense 
+	started	working correctly and made this a moot point - at least as far as intellisense is concerned.
+ 3) off_t notable exception - SeekDelegate, SeekHandleDelegate
+	Usually 2008clr functions are called by the callee, long long (clr 64bit long) can be marshaled and passed
+	to libmpg123. The seek delegate is called directly by the libmpg123 seek functions - there isn't an opportunity
+	to marshal the offending parameters. A library compiled in 32 bit will expect the SeekDelegate to have a 32bit
+	position parameter but in 64bit compilation the same parameter will be 64bit. Therefore the need to be correct
+	overrides the need for consistency with CLR 64bit positioners.
+	SIDE NOTE: In early tests the SeekDelegate was defined with a long long parameter - libmpg123 called it oblivious
+	to the fact that the type was incorrect. The only impact was that the 32bit position and 32bit origin (whence)
+	were compacted to a single 64bit parameter. This is fixed, no longer an issue!!!
+4)	PosixSeek and PosixRead ARE ONLY INCLUDED AS PROOF OF CONCEPT - to prove that the callbacks into CLR would
+	function correctly with libmpg123 cdecl calls. It saved making a separate dll for the posix elements.
+	REPEAT AFTER ME: Not for normal consumption....
+5)	The __clrcall decoration of mpg123clr functions is not strictly necessary for Visual Studio 2005 and later,
+	but has been left in for compatibility with earlier versions. See MS documentation of "double thunking"
+6)	Many functions use pin_ptr to pin the return variables prior to calling the libmpg123 function, this was
+	considered as an alternative to avoid the use of local variables with attendant overhead of 
+	allocate/use/copy/destroy etc. In practice pin_ptr has significant overhead, empirical tests showed very 
+	little performance difference between either method.
+7)	Set pin_ptr to NULL after use, to force early GC (recommended). Carried out performance trials and found
+	insignificant impact. Since most functions are likely to be used repeatedly decided to follow recommended usage.
+	If code analysis proves this to be redundant - can be removed...
+	(1.9.0.1 update) "insignificant" in Debug mode, quite significant if the debug overhead is removed, 
+	i.e. Release mode. So try/finally blocks removed in favour of allocating temporary local return variable.
+8)	(1.12.0.0 update) Support for mpg123_open_handle warrants further description... here it is.
+	a) Pinning of delegates is not required. See Microsoft: C++, How to: Marshal Callbacks and Delegates Using C++ Interop
+	b) Pinning of objects is an entirely different matter, so why is the open_handle object not pinned?
+	Answer: Because it's an object. I allowed passing of any object not just handles. 
+	i) a pin_ptr cannot be a field member for instance scope.
+	ii) cannot pin the object itself because there's no object.field to pin
+	iii) cannot pin the object target because the referenced object may be unblittable.
+	iv) GCHandle.Alloc(obj, GCHandleType.Pinned) doesn't work on unblittable objects (eg managed references like BinaryReader)
+	Since I don't restrict which objects may be passed I'm forced to exclude pinning.
+	c) The generated handle doesn't need to be pinned. GCHandle.Alloc(obj) creates a potentially GC relocatable object 
+	containing a Handle to the object. The GCHandle.ToIntPtr(userObjectHandle) creates an integer representation of the 
+	handle that is valid irrespective of any GC relocation of either the object or the GCHandle and can therefore be 
+	passed through unmanaged code to CLR native methods that can re-reference the original object via GCHandle.FromIntPtr 
+	and gch.Target.
+	All this seems relatively efficient, certainly there is little performance difference between the ReplaceReader
+	and ReplaceReaderHandle sample code.
+	
+=============================================================================
+Tested/Untested
+
+I haven't used mpg123clr in a production project yet, although one is about to start. Therefore EVERYTHING should
+be treated as though unproven. UPDATE: the scanclr, feedseekclr and replacereaderclr examples have provided a basic
+functional test.
+
+Largefile support totally untested... would appreciate a volunteer.
+
+The majority of functions have been tried in test projects with the following exceptions.
+
+64bit compilation.		mpg123clr compiles correctly in 64bit x64 platform mode, but hasn't been tested.
+
+ICY(icy_meta);			Never had genuine ICY data to test with.
+Icy2Utf8(icy_text);		Never tried. Please provide sample material.
+enc_from_id3(encbyte);	Works on libmpg123 enums, never had real world text samples.
+store_utf8(...);		Works with CLR generated text, not tried with real world text samples.
+mpg123str.strlen(...)	Not tested with utf8 text strings. Please provide sample material.
+
+==============================================================================
+Documentation
+
+mpg123clr is 90% documentation, use intellisense as your reference. If in doubt refer back to the libmpg123
+documents. NOTE: You need to build the mpg123clr library to create the intellisense file.
+
+===============================================================================
+Error Trapping
+
+libmpg123 is an error agnostic library - it shouldn't generate errors, but neither does it trap them.
+
+mpg123clr is built on the same concept although some CLR generated errors have been trapped. My personal
+preference is that exceptions should be avoided not relied on...
+
+THE CALLING APPLICATION IS RESPONSIBLE FOR ERROR DETECTION, TRAPPING AND CORRECTION.
+
+All projects are "as is" with no express or implied warranty. Demonstration projects are to demonstrate the 
+use of the library and are NOT considered examples of good coding practice. Use at own risk.
+
+===============================================================================
+Revision History
+
+	1.8.1.0	04-Aug-09	Initial release.
+	1.9.0.0 24-Sep-09	Function names harmonized with libmpg123 (mb)
+	1.9.0.0 30-Sep-09	Project config - if exists, copy libmpg123.dll to app output folder (mb)
+	1.9.0.0 01-Oct-09	Technical cleanup - subst nullptr for NULL (mb)
+	1.9.0.1	24-Nov-09	Performance update - removed try/finally (mb)
+	1.12.0.0 14-Apr-10	Release match - added open_handle and framebyframe support (mb)
+	1.13.0.0 13-Jan-11	Release match - added encsize and strlen support (mb)
+	
+Constructive feedback preferred.
+
+Malcolm Boczek
+mpg123clr original author.

data/mpg123/ports/MSVC++/2008clr/mpg123clr/advanced.cpp

@@ -0,0 +1,91 @@
+/*
+	mpg123clr: MPEG Audio Decoder library Common Language Runtime version.
+
+	copyright 2009 by Malcolm Boczek - free software under the terms of the LGPL 2.1
+	mpg123clr.dll is a derivative work of libmpg123 - all original mpg123 licensing terms apply.
+
+	All rights to this work freely assigned to the mpg123 project.
+*/
+/*
+	libmpg123: MPEG Audio Decoder library
+
+	copyright 1995-2008 by the mpg123 project - free software under the terms of the LGPL 2.1
+	see COPYING and AUTHORS files in distribution or http://mpg123.org
+
+*/
+/*
+	1.8.1.0	04-Aug-09	Initial release.
+	1.9.0.0 24-Sep-09	Function names harmonized with libmpg123 (mb)
+	1.9.0.0 13-Oct-09	pin_ptr = nullptr on return (mb)
+	1.9.0.1	24-Nov-09	performance update - removed try/finally (mb)
+*/
+
+#include "StdAfx.h"
+#include "advanced.h"
+
+mpg123clr::advpars::advpars(int% error)
+{
+	pin_ptr<int> err = &error;
+	mp = ::mpg123_new_pars(err);
+
+	err = nullptr;
+}
+
+mpg123clr::advpars::~advpars(void)
+{
+	// clean up code to release managed resources
+	// ...
+
+	// call Finalizer to clean up unmanaged resources
+	this->!advpars();
+}
+
+mpg123clr::advpars::!advpars(void)
+{
+	if (mp != NULL) 
+	{
+		::mpg123_delete_pars(mp);
+		mp = NULL;
+	}
+}
+
+mpg123clr::mpg::ErrorCode mpg123clr::advpars::mpg123_fmt_none(void)
+{
+	return (mpg123clr::mpg::ErrorCode) ::mpg123_fmt_none(mp);
+}
+
+mpg123clr::mpg::ErrorCode mpg123clr::advpars::mpg123_fmt_all(void)
+{
+	return (mpg123clr::mpg::ErrorCode) ::mpg123_fmt_all(mp);
+}
+
+mpg123clr::mpg::ErrorCode mpg123clr::advpars::mpg123_fmt(int rate, mpg123clr::mpg::channelcount channels, int encodings)
+{
+	return (mpg123clr::mpg::ErrorCode) ::mpg123_fmt(mp, rate, (int)channels, encodings);
+}
+
+mpg123clr::mpg::channelcount mpg123clr::advpars::mpg123_fmt_support(int rate, int encodings)
+{
+	return (mpg123clr::mpg::channelcount) ::mpg123_fmt_support(mp, rate, encodings);
+}
+
+mpg123clr::mpg::ErrorCode mpg123clr::advpars::mpg123_par(mpg123clr::mpg::parms type, int val, double fval)
+{
+	return (mpg123clr::mpg::ErrorCode) ::mpg123_par(mp, (mpg123_parms) type, val, fval);
+}
+
+mpg123clr::mpg::ErrorCode mpg123clr::advpars::mpg123_getpar(mpg123clr::mpg::parms type, [Out] int% val, [Out] double% fval)
+{
+	// Avoid need for local intermediary variables
+	pin_ptr<int> _val = &val;
+	pin_ptr<double> _fval = &fval;
+
+	int ret = ::mpg123_getpar(mp, (mpg123_parms) type, (long*)_val, _fval);
+
+	_fval = nullptr;
+	_val = nullptr;
+	
+	return (mpg123clr::mpg::ErrorCode) ret;
+}
+
+