Add back removed APIs from the TileDB.Interop namespace. (#278)

* Add back removed APIs from the `TileDB.Interop` namespace. (#277)

* Fix compile errors by making some interop types public again.

* Obsolete the reintroduced interop APIs, with a new diagnostic ID.

docs/obsoletions.md

@@ -7,6 +7,7 @@ Following [the deprecation policy of TileDB Embedded][core-deprecation], obsolet
 |Diagnostic codes|Deprecated in version|Removed in version|
 |----------------|---------------------|------------------|
 |[`TILEDB0001`](#TILEDB0001) …[`TILEDB0011`](#TILEDB0011)|5.3.0|5.5.0|
+|[`TILEDB0012`](#TILEDB0012) …[`TILEDB0012`](#TILEDB0012)|5.7.0|5.9.0|
 
 ## `TILEDB0001` - Enum value names that start with `TILEDB_` were replaced with C#-friendly names.
 
@@ -299,4 +300,23 @@ Some of these methods were renamed or had their signature changed (for example t
 
 Instead of setting ranges and subarrays on the `Query`, create and configure a `Subarray` object, and assign it to the query using the `Query.SetSubarray` method.
 
+## `TILEDB0012` - Members of the `TileDB.Interop` namespace will become internal in a future version and should not be used by user code.
+
+<a name="TILEDB0012"></a>
+
+Some APIs in the `TileDB.Interop` namespace that were inadvertently removed in version 5.3.0 were reintroduced in version 5.7.0. They are marked as obsolete and hidden from IntelliSense and will be removed from the public API for good in version 5.9.0. They were also reintroduced in patch releases 5.3.1 and 5.4.1, obsoleted under the [`TILEDB0003`](#TILEDB0003) code.
+
+### Version introduced
+
+5.7.0
+
+### Recommended action
+
+The obsoleted APIs fall into the following categories:
+
+- The `MarshaledString` and `MarshaledStringOut` types are used to help convert strings from and to ASCII and pass them to native code. If you are using them in user code for native code interop, you should use .NET's [built-in P/Invoke](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/charset) marshaling instead. For other kinds of encoding conversions, you should use APIs from the [`System.Text.Encoding`](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding) class.
+- The `__sFile` and `LibC` types have no members and there is no reason to use them anyway.
+- The types that derive from `SafeHandle` are used to safely manage the lifetime of native TileDB objects. With the APIs in the `TileDB.CSharp` namespace providing broad coverage of TileDB's functionalities while also being safer and easier to sue, these types provide limited utility. You should use the APIs in the `TileDB.CSharp` namespace instead.
+- Types with the name `tiledb_***_t` were made public again only to support the APIs of the safe handles above. They have little other use on their own. You should use APIs in the `TileDB.CSharp` namespace instead.
+
 [core-deprecation]: https://github.com/TileDB-Inc/TileDB/blob/dev/doc/policy/api_changes.md

sources/TileDB.CSharp/Array.cs

@@ -5,6 +5,9 @@
 using TileDB.CSharp.Marshalling;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ArrayHandle = TileDB.CSharp.Marshalling.SafeHandles.ArrayHandle;
+using ArraySchemaHandle = TileDB.CSharp.Marshalling.SafeHandles.ArraySchemaHandle;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/ArraySchema.cs

@@ -2,6 +2,10 @@
 using System.Collections.Generic;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ArraySchemaHandle = TileDB.CSharp.Marshalling.SafeHandles.ArraySchemaHandle;
+using FilterListHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterListHandle;
+using DomainHandle = TileDB.CSharp.Marshalling.SafeHandles.DomainHandle;
+using AttributeHandle = TileDB.CSharp.Marshalling.SafeHandles.AttributeHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/ArraySchemaEvolution.cs

@@ -1,6 +1,7 @@
 using System;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ArraySchemaEvolutionHandle = TileDB.CSharp.Marshalling.SafeHandles.ArraySchemaEvolutionHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Attribute.cs

@@ -2,8 +2,10 @@
 using System.Linq;
 using System.Runtime.InteropServices;
 using System.Text;
-using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using TileDB.CSharp.Marshalling.SafeHandles;
+using AttributeHandle = TileDB.CSharp.Marshalling.SafeHandles.AttributeHandle;
+using FilterListHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterListHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Config.cs

@@ -2,6 +2,7 @@
 using System.Text;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/ConfigIterator.cs

@@ -1,6 +1,8 @@
 using System;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
+using ConfigIteratorHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigIteratorHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Context.cs

@@ -7,6 +7,8 @@
 using System.Text;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ContextHandle = TileDB.CSharp.Marshalling.SafeHandles.ContextHandle;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Dimension.cs

@@ -4,6 +4,8 @@
 using TileDB.CSharp.Marshalling;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using DimensionHandle = TileDB.CSharp.Marshalling.SafeHandles.DimensionHandle;
+using FilterListHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterListHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Domain.cs

@@ -1,6 +1,8 @@
 using System;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using DomainHandle = TileDB.CSharp.Marshalling.SafeHandles.DomainHandle;
+using DimensionHandle = TileDB.CSharp.Marshalling.SafeHandles.DimensionHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/File.cs

@@ -1,6 +1,7 @@
 using System.ComponentModel;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ArraySchemaHandle = TileDB.CSharp.Marshalling.SafeHandles.ArraySchemaHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Filter.cs

@@ -3,6 +3,7 @@
 using System.Runtime.InteropServices;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using FilterHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/FilterList.cs

@@ -1,6 +1,8 @@
 using System;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using FilterHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterHandle;
+using FilterListHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterListHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/FragmentInfo.cs

@@ -3,6 +3,8 @@
 using TileDB.CSharp.Marshalling;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using ArraySchemaHandle = TileDB.CSharp.Marshalling.SafeHandles.ArraySchemaHandle;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Group.cs

@@ -1,6 +1,8 @@
 using System;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using TileDB.Interop;
+using GroupHandle = TileDB.CSharp.Marshalling.SafeHandles.GroupHandle;
+using ConfigHandle = TileDB.CSharp.Marshalling.SafeHandles.ConfigHandle;
 
 namespace TileDB.CSharp
 {

sources/TileDB.CSharp/Interop/InteropAux.cs

@@ -0,0 +1,13 @@
+using System.ComponentModel;
+using System;
+using TileDB.CSharp;
+
+namespace TileDB.Interop
+{
+    [Obsolete(Obsoletions.TileDBInterop2Message, DiagnosticId = Obsoletions.TileDBInterop2DiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    // placeholder struct to avoid errors loading generated code
+    public partial struct __sFILE
+    {
+    }
+}

sources/TileDB.CSharp/Interop/SpanExtensions.cs

@@ -0,0 +1,31 @@
+// Copyright (c) .NET Foundation and Contributors. All Rights Reserved. Licensed under the MIT License (MIT). See License.md in the repository root for more information.
+//https://github.com/dotnet/ClangSharp/blob/67c1e5243b9d58f2b28f10e3f9a82f7537fd9d88/sources/ClangSharp.Interop/Internals/SpanExtensions.cs
+
+using System;
+using System.ComponentModel;
+using System.Text;
+using TileDB.CSharp;
+
+namespace TileDB.Interop
+{
+    [Obsolete(Obsoletions.TileDBInteropMessage, DiagnosticId = Obsoletions.TileDBInteropDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public static unsafe class SpanExtensions
+    {
+        public static string AsString(this Span<byte> self) => AsString((ReadOnlySpan<byte>)self);
+
+        public static string AsString(this ReadOnlySpan<byte> self)
+        {
+            if (self.IsEmpty)
+            {
+                return string.Empty;
+            }
+
+            fixed (byte* pSelf = self)
+            {
+                return Encoding.ASCII.GetString(pSelf, self.Length);
+            }
+        }
+    }
+
+}//namespace