Renamed TwainSession to TwainAppSession. I love renaming things.

README.md

@@ -1,22 +1,23 @@
 # TWAIN dotnet library
 
-NOTE: This is a rewrite test that internally uses parts of
-[twaincs](https://github.com/twain/twain-cs) from
-the TWAIN Working Group. It doesn't fully work yet.
+NOTE: This is a rewrite test that doesn't fully work yet.
 Use V3 branch for the current version.
 
 ## Info
 
 This is a dotnet library created to make working with 
 [TWAIN](http://twain.org/) devices easier in dotnet. 
-V4 of this lib has these goals:
+It internally uses some parts of the
+[twaincs](https://github.com/twain/twain-cs) code from
+the TWAIN Working Group.
+V4 of this lib has these features:
 
 * Targets latest TWAIN version (2.5).
-* Supports full framework and netcore apps (if the framework is still supported).
+* Runs under full framework (4.6.2+) and netcore variants (6.0+).
 
 ## Using the lib
 
-Before using this lib, you are recommended to become reasonably 
+Before using this lib, you are required to be reasonably 
 familiar with the TWAIN spec and understand how it works in general. 
 The TWAIN spec can be downloaded from [twain.org](http://twain.org/). 
 

samples/WinForm32/Form1.cs

@@ -10,7 +10,7 @@ namespace WinForm32
 {
   public partial class Form1 : Form
   {
-    private TwainSession twain;
+    private TwainAppSession twain;
 
     public Form1()
     {
@@ -18,7 +18,7 @@ namespace WinForm32
       Text += TwainPlatform.Is32bit ? " 32bit" : " 64bit";
       TwainPlatform.PreferLegacyDSM = false;
 
-      twain = new TwainSession(new WinformMarshaller(this), Assembly.GetExecutingAssembly().Location);
+      twain = new TwainAppSession(new WinformMarshaller(this), Assembly.GetExecutingAssembly().Location);
       twain.StateChanged += Twain_StateChanged;
       twain.DefaultSourceChanged += Twain_DefaultSourceChanged;
       twain.CurrentSourceChanged += Twain_CurrentSourceChanged;
@@ -31,17 +31,17 @@ namespace WinForm32
       twain.Dispose();
     }
 
-    private void Twain_CurrentSourceChanged(TwainSession arg1, TW_IDENTITY_LEGACY ds)
+    private void Twain_CurrentSourceChanged(TwainAppSession arg1, TW_IDENTITY_LEGACY ds)
     {
       lblCurrent.Text = ds.ProductName;
     }
 
-    private void Twain_DefaultSourceChanged(TwainSession arg1, TW_IDENTITY_LEGACY ds)
+    private void Twain_DefaultSourceChanged(TwainAppSession arg1, TW_IDENTITY_LEGACY ds)
     {
       lblDefault.Text = ds.ProductName;
     }
 
-    private void Twain_StateChanged(TwainSession session, STATE state)
+    private void Twain_StateChanged(TwainAppSession session, STATE state)
     {
       lblState.Text = state.ToString();
     }

src/NTwain/DSM/DSMGenerator.tt

@@ -6,14 +6,14 @@
 <#@ import namespace="System.Collections.Generic" #>
 <#@ output extension="dummy" #>
 <#
-List<(string className, string dllPath, string identityClass)> outputs = new() {
- ("OSXLegacyDSM", "/System/Library/Frameworks/framework/TWAIN", "TW_IDENTITY_MACOSX"),
- ("OSXNewDSM", "/Library/Frameworks/TWAINDSM.framework/TWAINDSM", "TW_IDENTITY_MACOSX"),
- ("LinuxDSM", "/usr/local/lib/libtwaindsm.so", "TW_IDENTITY_LEGACY"),
- ("Linux64DSM", "/usr/local/lib64/libtwaindsm.so", "TW_IDENTITY_LEGACY"),
- ("LinuxBotched64DSM", "/usr/local/lib/libtwaindsm.so.2.3.2", "TW_IDENTITY"),
- ("WinLegacyDSM", "twain_32.dll", "TW_IDENTITY_LEGACY"),
- ("WinNewDSM", "twaindsm.dll", "TW_IDENTITY_LEGACY")
+List<(string className, string dllPath, string identityClass, string addlInfo)> outputs = new() {
+ ("OSXLegacyDSM", "/System/Library/Frameworks/framework/TWAIN", "TW_IDENTITY_MACOSX", ""),
+ ("OSXNewDSM", "/Library/Frameworks/TWAINDSM.framework/TWAINDSM", "TW_IDENTITY_MACOSX", ""),
+ ("LinuxDSM", "/usr/local/lib/libtwaindsm.so", "TW_IDENTITY_LEGACY", ""),
+ ("Linux64DSM", "/usr/local/lib64/libtwaindsm.so", "TW_IDENTITY_LEGACY", "For versions since 2.4."),
+ ("LinuxBotched64DSM", "/usr/local/lib/libtwaindsm.so.2.3.2", "TW_IDENTITY", "For versions before 2.4."),
+ ("WinLegacyDSM", "twain_32.dll", "TW_IDENTITY_LEGACY", "For 32bit only."),
+ ("WinNewDSM", "twaindsm.dll", "TW_IDENTITY_LEGACY", "")
 };
 
 foreach(var file in outputs) {
@@ -25,7 +25,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using <#= file.dllPath #>.
+  /// Low-level pinvoke methods using <#= file.dllPath #>. <#= file.addlInfo #>
   /// </summary>
   public static class <#= file.className #>
   {

src/NTwain/DSM/Linux64DSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using /usr/local/lib64/libtwaindsm.so.
+  /// Low-level pinvoke methods using /usr/local/lib64/libtwaindsm.so. For versions since 2.4.
   /// </summary>
   public static class Linux64DSM
   {

src/NTwain/DSM/LinuxBotched64DSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using /usr/local/lib/libtwaindsm.so.2.3.2.
+  /// Low-level pinvoke methods using /usr/local/lib/libtwaindsm.so.2.3.2. For versions before 2.4.
   /// </summary>
   public static class LinuxBotched64DSM
   {

src/NTwain/DSM/LinuxDSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using /usr/local/lib/libtwaindsm.so.
+  /// Low-level pinvoke methods using /usr/local/lib/libtwaindsm.so. 
   /// </summary>
   public static class LinuxDSM
   {

src/NTwain/DSM/OSXLegacyDSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using /System/Library/Frameworks/framework/TWAIN.
+  /// Low-level pinvoke methods using /System/Library/Frameworks/framework/TWAIN. 
   /// </summary>
   public static class OSXLegacyDSM
   {

src/NTwain/DSM/OSXNewDSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using /Library/Frameworks/TWAINDSM.framework/TWAINDSM.
+  /// Low-level pinvoke methods using /Library/Frameworks/TWAINDSM.framework/TWAINDSM. 
   /// </summary>
   public static class OSXNewDSM
   {

src/NTwain/DSM/WinLegacyDSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using twain_32.dll.
+  /// Low-level pinvoke methods using twain_32.dll. For 32bit only.
   /// </summary>
   public static class WinLegacyDSM
   {

src/NTwain/DSM/WinNewDSM.cs

@@ -5,7 +5,7 @@ using System.Runtime.InteropServices;
 namespace NTwain.DSM
 {
   /// <summary>
-  /// Low-level pinvoke methods using twaindsm.dll.
+  /// Low-level pinvoke methods using twaindsm.dll. 
   /// </summary>
   public static class WinNewDSM
   {

src/NTwain/Data/TWAINH_EXTRAS.cs

@@ -724,8 +724,7 @@ namespace NTwain.Data
 
             //// unsafe method with 1 copy (does it work?)
             //sbyte* bytes = (sbyte*)locked;
-            //var str = new string(bytes, 0, length, Encoding.UTF8);
-            //return str;
+            //val = new string(bytes, 0, length, Encoding.UTF8);
 #else
             val = Marshal.PtrToStringUTF8(locked, (int)Size);
 #endif

src/NTwain/ThreadMarshaller.Windows.cs

@@ -7,7 +7,7 @@ namespace NTwain
 {
   /// <summary>
   /// An <see cref="IThreadMarshaller"/> that can be used
-  /// to integrate <see cref="TwainSession"/> with
+  /// to integrate <see cref="TwainAppSession"/> with
   /// an existing Winforms app.
   /// </summary>
   public class WinformMarshaller : IThreadMarshaller
@@ -32,7 +32,7 @@ namespace NTwain
 
   /// <summary>
   /// An <see cref="IThreadMarshaller"/> that can be used
-  /// to integrate <see cref="TwainSession"/> with
+  /// to integrate <see cref="TwainAppSession"/> with
   /// an existing WPF app.
   /// </summary>
   public class WpfMarshaller : IThreadMarshaller

src/NTwain/Triplets/Readme.md

@@ -1,21 +1,20 @@
 All TWAIN operations are done through the a combination of 
 Data Group (DG), Data Argument Type (DAT), and Message (MSG) 
 triplets. Rather than dealing with all the combinations 
-directly and risk passing the wrong thing, all valid triplet 
-combinations are simply made available under this namespace.
+directly in the DSM pinvokes and risk passing the wrong thing, 
+all valid triplet combinations are made available under this namespace.
 
 Example:
-To get the status of the DS, just use the 
-"Get" method (represents MSG), in the
-"Status" property (represnts DAT), in the
-"DGControl" class (represents DG).
+To get the status of the DS, the triplet is
+`DG_Control / DAT_STATUS / MSG_GET` in the documentation. 
+With this wrapper you can use a similar call path:
 
-or better explained in code:
+```cs
+DGControl.Status.Get(...);
+```
 
-DGControl.Status.Get(...)
+Only triplets usable by the application-side are defined here.
 
-Only triplets usable by the
-application-side are defined here.
-
-These are still low-level calls and TwainSession is the higher
-level abstraction with some state keeping and other checks for ease of use.
+These are still relatively low-level calls and `TwainAppSession` is the next higher
+level abstraction with some state keeping and other dotnet-friendly methods
+and events for regular use.

src/NTwain/TwainAppSession.Callbacks.cs

@@ -8,7 +8,7 @@ namespace NTwain
 {
   // this file contains callback methods
 
-  partial class TwainSession
+  partial class TwainAppSession
   {
 
     delegate ushort LegacyIDCallbackDelegate(

src/NTwain/TwainAppSession.Caps.cs

@@ -7,7 +7,7 @@ namespace NTwain
 {
   // this file contains capability mgmt methods
 
-  partial class TwainSession
+  partial class TwainAppSession
   {
     ///// <summary>
     ///// Gets all the supported caps for the current source.

src/NTwain/TwainAppSession.Memory.cs

@@ -7,7 +7,7 @@ namespace NTwain
 {
   // this file contains memory methods
 
-  partial class TwainSession : IMemoryManager
+  partial class TwainAppSession : IMemoryManager
   {
     internal TW_ENTRYPOINT_DELEGATES _entryPoint;
 

src/NTwain/TwainAppSession.PropEvents.cs

@@ -7,7 +7,7 @@ namespace NTwain
 {
   // this file contains property and event definitions
 
-  partial class TwainSession
+  partial class TwainAppSession
   {
     /// <summary>
     /// Gets the app identity.
@@ -119,22 +119,22 @@ namespace NTwain
     /// <summary>
     /// Fires when <see cref="State"/> changes.
     /// </summary>
-    public event Action<TwainSession, STATE>? StateChanged;
+    public event Action<TwainAppSession, STATE>? StateChanged;
 
     /// <summary>
     /// Fires when <see cref="DefaultSource"/> changes.
     /// </summary>
-    public event Action<TwainSession, TW_IDENTITY_LEGACY>? DefaultSourceChanged;
+    public event Action<TwainAppSession, TW_IDENTITY_LEGACY>? DefaultSourceChanged;
 
     /// <summary>
     /// Fires when <see cref="CurrentSource"/> changes.
     /// </summary>
-    public event Action<TwainSession, TW_IDENTITY_LEGACY>? CurrentSourceChanged;
+    public event Action<TwainAppSession, TW_IDENTITY_LEGACY>? CurrentSourceChanged;
 
     /// <summary>
     /// Fires when the source has some device event happening.
     /// </summary>
-    public event Action<TwainSession, TW_DEVICEEVENT>? DeviceEvent;
+    public event Action<TwainAppSession, TW_DEVICEEVENT>? DeviceEvent;
 
     /// <summary>
     /// Fires when there's an error during transfer.

src/NTwain/TwainAppSession.Sources.cs

@@ -6,7 +6,7 @@ namespace NTwain
 {
   // this file contains data source utilities
 
-  partial class TwainSession
+  partial class TwainAppSession
   {
     /// <summary>
     /// Gets all available sources.

src/NTwain/TwainAppSession.Windows.cs

@@ -15,7 +15,7 @@ namespace NTwain
 
   // contains parts for winform/wpf message loop integration
 
-  partial class TwainSession : IMessageFilter
+  partial class TwainAppSession : IMessageFilter
   {
     HwndSource? _wpfhook;
 

src/NTwain/TwainAppSession.Xfers.cs

@@ -10,7 +10,7 @@ namespace NTwain
 {
   // this file contains various xfer methods
 
-  partial class TwainSession
+  partial class TwainAppSession
   {
     /// <summary>
     /// Start the transfer loop.

src/NTwain/TwainAppSession.cs

@@ -11,7 +11,7 @@ namespace NTwain
 {
   // this file contains initialization/cleanup things.
 
-  public partial class TwainSession : IDisposable
+  public partial class TwainAppSession : IDisposable
   {
     static bool __encodingRegistered;
 
@@ -22,7 +22,7 @@ namespace NTwain
     /// <param name="exeFilePath"></param>
     /// <param name="appLanguage"></param>
     /// <param name="appCountry"></param>
-    public TwainSession(IThreadMarshaller uiThreadMarshaller,
+    public TwainAppSession(IThreadMarshaller uiThreadMarshaller,
       string exeFilePath,
       TWLG appLanguage = TWLG.ENGLISH_USA, TWCY appCountry = TWCY.USA) :
       this(uiThreadMarshaller, FileVersionInfo.GetVersionInfo(exeFilePath), appLanguage, appCountry)
@@ -34,7 +34,7 @@ namespace NTwain
     /// <param name="appInfo"></param>
     /// <param name="appLanguage"></param>
     /// <param name="appCountry"></param>
-    public TwainSession(IThreadMarshaller uiThreadMarshaller,
+    public TwainAppSession(IThreadMarshaller uiThreadMarshaller,
         FileVersionInfo appInfo,
         TWLG appLanguage = TWLG.ENGLISH_USA, TWCY appCountry = TWCY.USA) :
         this(uiThreadMarshaller,
@@ -56,7 +56,7 @@ namespace NTwain
     /// <param name="appLanguage"></param>
     /// <param name="appCountry"></param>
     /// <param name="supportedTypes"></param>
-    public TwainSession(IThreadMarshaller uiThreadMarshaller,
+    public TwainAppSession(IThreadMarshaller uiThreadMarshaller,
         string companyName, string productFamily, string productName,
         Version productVersion, string productDescription = "",
         TWLG appLanguage = TWLG.ENGLISH_USA, TWCY appCountry = TWCY.USA,