Workshop 8 - interop

content/labs/lab14/index.en.md

@@ -0,0 +1,88 @@
+---
+title: "Lab14"
+weight: 10
+---
+
+# Laboratory 14: Interoperability, Marshalling, Unsafe context
+
+## Safe handles
+
+Create a program reading files using external functions from native system libraries.
+
+### Starting code
+
+> [!NOTE]
+> **Student**
+> {{< filetree dir="labs/lab14/student/SafeHandles" >}}
+
+### Task description
+
+Caution is required when interacting with code that is not [managed](https://csharp.mini.pw.edu.pl/en/lectures/01.introduction/#main-features-of-the-language) - e.g. base C++, C. Safety measures provided by the .NET environment stop guaranteeing protection the moment code calls into external code. Structures created in unmanaged code are often represented by pointers or other identifiers that have unique values reserved for invalid states (commonly 0 or -1). Use classes inheriting from `SafeHandle` to make sure that resources you requested are valid before use.
+
+A partially implemented class that imports system functions for handling files can be found in the `FileInteraction` project - in `WindowsFile.cs` or `UnixFile.cs` depending which operating system you use. Only the relevant one will be used for compilation. Take a look at the project file `FileInteraction.csproj` - conditional exclusion of the file that doesn't match your system is implemented for you.
+
+Check what values the file opening function declares as invalid. Make the `MyFile` class inherit from the correct `SafeHandle` so it matches the invalid values. Make sure you do it in `WindowsFile.cs` if you're on Windows or `UnixFile.cs` if you're on OSX or Linux. Finish the correct implementation for your system. Fill in `Open` and `Read` in the file `MyFile.cs`. You can test the program by running it.
+
+After the workshop you're encouraged to try this task for the other operating system setup.
+
+{{% hint info %}}
+**Useful links:**
+
+- [Microsoft Learn: MSBuild conditions](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-conditions)
+- [Microsoft Learn: SafeHandles namespace](https://learn.microsoft.com/en-us/dotnet/api/microsoft.win32.safehandles?view=net-9.0)
+- [POSIX Manual: open](https://www.man7.org/linux/man-pages/man3/open.3p.html)
+- [Microsoft Learn: CreateFile](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea)
+
+
+{{% /hint %}}
+
+
+### Example solution
+
+> [!TIP]
+> **Solution**
+> {{< filetree dir="labs/lab14/solution/SafeHandles" >}}
+
+## Binding and Marshalling
+
+Use an unmanaged library to create visual patterns.
+
+### Starting code
+
+> [!NOTE]
+> **Student**
+> {{< filetree dir="labs/lab14/student/Binding" >}}
+
+### Task description
+
+Import the functions shared in `pattern.h` using `LibraryImport` in the `PatternGeneration` project, `NativeMethods.cs`. Declare all required classes and structures. Implement wrapping functions in the `Pattern` class (`Pattern.cs`) so that the library user only has to interact with managed functions.
+- Some arguments might require the `[In]` attribute to specify the direction of information exchange. Similarily, if there was a change in an argument that needed to be shown back to the caller, the `[Out]` tag would be appropriate.
+- Structures on the managed side of the interaction need to be laid out precisely like the ones on the unmanaged side. Alternatively, one can define custom marshalling. That requires the programmer to define rules for turning the unmanaged structures into their managed counterparts and vice versa using the [`CustomMarshaller`](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/tutorial-custom-marshaller) attribute.
+- Treat the `pattern_t` structure as opaque. Simply treat its pointer as one of the `SafeHandles` and don't worry about transfering data. Use the handle itself for calling the other imported functions, especially after you implement the inheritance.
+
+The library distributors might not release the full internal data layout for the user. The user might care about only a small part of the structure and not need it whole. Use `Marshall.Copy` in the `GetImage` function (`Pattern.cs`) to extract the dimensions and contents of the `color_t[] values` array hidden under the opaque handle. Utilise the fact that the fields will be laid out sequentially like in `pattern.h` (with offset 0, then offset `sizeof(int)` and `sizeof(int)*2`). The struct `color_t` has the same layout as the `Rgb24` structure. Use the acquired data to create an image with  `Image.LoadPixelData<Rgb24>`.
+
+Fill in the `Main` function in the `PatternGenerationDemo` project to create at least one image each with the functions `pattern_enstripen` and `pattern_populate`. 
+
+{{% hint info %}}
+**Useful links:**
+
+- [Microsoft Learn: P/Invoke](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/pinvoke-source-generation)
+- [Microsoft Learn: Struct layout](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.structlayoutattribute?view=net-9.0)
+- [Microsoft Learn: Type marshalling](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/type-marshalling)
+- [Microsoft Learn: Built-in type marshalling](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.disableruntimemarshallingattribute?view=net-9.0)
+
+
+{{% /hint %}}
+
+### Example results
+`populate`
+![populate](Data/Image1.png)
+`enstripen`
+![enstripen](Data/Image2.png)
+
+### Example solution
+
+> [!TIP]
+> **Solution**
+> {{< filetree dir="labs/lab14/solution/Binding" >}}

content/labs/lab14/index.pl.md

@@ -0,0 +1,85 @@
+---
+title: "Lab14"
+weight: 10
+---
+
+# Laboratorium 14: Współdziałanie, Marshalling, Kontekst Niebezpieczny
+
+## Bezpieczne uchwyty
+
+Celem zadania jest stworzenie programu odczytującego pliki z użyciem zewnętrznych funkcji pochodzących z bibliotek systemowych.
+
+### Kod początkowy
+
+> [!NOTE]
+> **Student**
+> {{< filetree dir="labs/lab14/student/SafeHandles" >}}
+
+### Opis zadania
+
+Współpraca z kodem o ręcznym zarządzaniu pamięci - jak np. napisanym w C++ lub C - wymaga ostrożności przy wymianie informacji. Zabezpieczenia które zapewnia nam platforma .NET tracą siłę w momencie przejścia do kodu zewnętrznego. Struktury tworzone w takim kodzie często przekazywane są w postaci wskaźników lub innych identyfikatorów które posiadają szczególne wartości sygnalizujące błąd (często 0 lub -1). Użyj klas dziedziczących po `SafeHandle`, aby upewnić się że zasoby zostały poprawnie przekazane przed ich użyciem.
+
+W projekcie `FileInteraction` znajdziesz częściowo zaimplementowaną klasę ładującą funkcje systemowe obsługujące pliki - zależnie od systemu operacyjnego odpowiednio w pliku `WindowsFile.cs` oraz `UnixFile.cs`. Tylko ta, która odpowiada Twojemu systemowi będzie dołączona do skompilowanego programu. Zwróć uwagę na plik projektu `FileInteraction.csproj`, już za Ciebie użyte w nim zostało warunkowe wykluczenie niepasującego pliku źródłowego. 
+
+Sprawdź jakie wartości zwracane przez funkcję otwierającą plik powinny być interpretowane jako niewłaściwe. Dokończ implementację części odpowiadającej systemowi którego używasz. Dodaj do klasy `MyFile` w pliku `WindowsFile.cs` lub `UnixFile.cs` dziedziczenie po odpowiedniej klasie z rodziny `SafeHandle` i zaimplementuj potrzebne funkcje. W pliku `MyFile.cs` uzupełnij funkcje `Open` oraz `Read`. Program możesz przetestować uruchamiając go.
+
+Po zakończeniu zajęć zachęcamy do próby wykonania zadania na innym systemie operacyjnym.
+
+{{% hint info %}}
+**Materiały pomocnicze:**
+
+- [Microsoft Learn: MSBuild conditions](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-conditions)
+- [Microsoft Learn: SafeHandles namespace](https://learn.microsoft.com/en-us/dotnet/api/microsoft.win32.safehandles?view=net-9.0)
+- [POSIX Manual: open](https://www.man7.org/linux/man-pages/man3/open.3p.html)
+- [Microsoft Learn: CreateFile](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea)
+
+{{% /hint %}}
+
+### Przykładowe rozwiązanie
+
+> [!TIP]
+> **Rozwiązanie**
+> {{< filetree dir="labs/lab14/solution/SafeHandles" >}}
+
+## Wiązania oraz Marshalling
+Celem zadania jest użycie biblioteki niezarządzanej do stworzenia wzoru graficznego.
+
+### Kod początkowy
+
+> [!NOTE]
+> **Student**
+> {{< filetree dir="labs/lab14/student/Binding" >}}
+
+### Opis zadania
+
+W projekcie `PatternGeneration`, pliku `NativeMethods.cs` zaimportuj za pomocą `LibraryImport` funkcje, które udostępnia plik `pattern.h`. Zadeklaruj również wszystkie potrzebne dla nich struktury i klasy. Następnie zaimplementuj w klasie `Pattern` w `Pattern.cs` funkcje opakowujące, które pozwolą konsumentowi biblioteki wchodzić w interakcję jedynie z zarządzanym kodem.
+- Niektóre argumenty wymagają dodania atrybutu `[In]`, aby sprecyzować kierunek wymiany danych. Analogicznie, jeśli jeden z argumentów podległby zmianie wewnątrz funkcji i potrzebne byłoby odzwierciedlenie tych zmian po stronie wywołującego, stosowny byłby atrybut `[Out]`.
+- Struktury po stronie zarządzanej muszą mieć określone ułożenie pól ściśle zgodne ze strukturami, aby marshalling dokonywał się automatycznie. Alternatywą jest ręczny marshalling, do którego potrzebne jest zdefiniowanie reguł zmiany danych niezarządzanych w klasę lub strukturę zarządzaną z użyciem atrybutu [`CustomMarshaller`](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/tutorial-custom-marshaller).
+- Potraktuj strukturę `pattern_t` jako nieprzejrzystą (ang. opaque). Nie martw się przenoszeniem danych. Wystarczy potraktować wskaźnik tej struktury jako jeden z `SafeHandle` do wywoływania innych funkcji, analogicznie do poprzedniego zadania.
+
+Dystrybutor biblioteki może czasem nie udostępniać całego rozkładu struktury lub przenoszenie wszystich danych przez barierę biblioteka-aplikacja może nie być potrzebne. W funkcji `GetImage` w `Pattern.cs` użyj funkcji `Marshall.Copy`, aby wydobyć dane o wymiarach oraz zawartości tablicy `color_t[] values` ukrytej pod nieprzejrzystem uchwytem. Zwróć uwagę na to, że pola ułożone będą po kolei tak jak w `pattern.h` (a więc kolejno z przesunięciem 0, `sizeof(int)`, `2*sizeof(int)`), a struktura `color_t` odpowiada bezpośrednio strukturze `Rgb24`. Użyj pozyskanych danych do stworzenia obrazu z `Image.LoadPixelData<Rgb24>`.
+
+Uzupełnij funkcję `Main` w projekcie `PatternGenerationDemo` aby tworzyło się co najmniej po jednym obrazie z użyciem fukcji `pattern_enstripen` oraz `pattern_populate`.
+
+{{% hint info %}}
+**Materiały pomocnicze:**
+
+- [Microsoft Learn: P/Invoke](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/pinvoke-source-generation)
+- [Microsoft Learn: Struct layout](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.structlayoutattribute?view=net-9.0)
+- [Microsoft Learn: Type marshalling](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/type-marshalling)
+- [Microsoft Learn: Built-in type marshalling](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.disableruntimemarshallingattribute?view=net-9.0)
+
+
+{{% /hint %}}
+
+### Przykładowy rezultat
+`populate`
+![populate](Data/Image1.png)
+`enstripen`
+![enstripen](Data/Image2.png)
+
+### Przykładowe rozwiązanie
+
+> [!TIP]
+> **Rozwiązanie**
+> {{< filetree dir="labs/lab14/solution/Binding" >}}

static/labs/lab14/solution/Binding/Binding.sln

@@ -0,0 +1,31 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.14.36811.4 d17.14
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PatternGeneration", "PatternGeneration\PatternGeneration.csproj", "{0BAF5E86-AE4D-D0FE-43AF-765BA1F81D35}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PatternGenerationDemo", "PatternGenerationDemo\PatternGenerationDemo.csproj", "{85A2E662-3F5B-43A7-91FD-3205C4837ACB}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{0BAF5E86-AE4D-D0FE-43AF-765BA1F81D35}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0BAF5E86-AE4D-D0FE-43AF-765BA1F81D35}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0BAF5E86-AE4D-D0FE-43AF-765BA1F81D35}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0BAF5E86-AE4D-D0FE-43AF-765BA1F81D35}.Release|Any CPU.Build.0 = Release|Any CPU
+		{85A2E662-3F5B-43A7-91FD-3205C4837ACB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{85A2E662-3F5B-43A7-91FD-3205C4837ACB}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{85A2E662-3F5B-43A7-91FD-3205C4837ACB}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{85A2E662-3F5B-43A7-91FD-3205C4837ACB}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {D6DF6AAC-0198-4959-BBDA-1CABB72333E4}
+	EndGlobalSection
+EndGlobal

static/labs/lab14/solution/Binding/PatternGeneration/NativeMethods.cs

@@ -0,0 +1,17 @@
+using System.Drawing;
+using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
+using PatternGeneration;
+
+internal static partial class NativeMethods
+{
+    private const string LibName = "pg";
+    [LibraryImport(LibName)]
+    public static partial nint pattern_init(int width, int height);
+    [LibraryImport(LibName)]
+    public static partial void pattern_populate(Pattern pattern, [In] PatternGeneration.Point[] points, int n);
+    [LibraryImport(LibName)]
+    public static partial void pattern_enstripen(Pattern pattern, StripeSettings settings);
+    [LibraryImport(LibName)]
+    public static partial void pattern_destroy(Pattern pattern);
+}

static/labs/lab14/solution/Binding/PatternGeneration/Pattern.cs

@@ -0,0 +1,43 @@
+using Microsoft.Win32.SafeHandles;
+using SixLabors.ImageSharp;
+using SixLabors.ImageSharp.PixelFormats;
+using System;
+using System.Collections.Generic;
+using System.Drawing;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PatternGeneration
+{
+    public class Pattern : SafeHandleZeroOrMinusOneIsInvalid
+    {
+        public Pattern(int width, int height) : base(true)
+        {
+            handle = NativeMethods.pattern_init(width, height);
+        }
+
+        public void Populate(PatternGeneration.Point[] points)
+        {
+            NativeMethods.pattern_populate(this, points, points.Length);
+        }
+        public void Enstripen(StripeSettings settings)
+        {
+            NativeMethods.pattern_enstripen(this, settings);
+        }
+        public Image GetImage()
+        {
+            var dimensions = new int[2];
+            Marshal.Copy(handle, dimensions, 0, dimensions.Length);
+            var content = new byte[dimensions[0]*dimensions[1]*3];
+            Marshal.Copy(handle + sizeof(int) * 2, content, 0, content.Length);
+            return Image.LoadPixelData<Rgb24>(content, dimensions[0], dimensions[1]);
+        }
+        protected override bool ReleaseHandle()
+        {
+            NativeMethods.pattern_destroy(this);
+            return true;
+        }
+    }
+}

static/labs/lab14/solution/Binding/PatternGeneration/PatternGeneration.csproj

@@ -0,0 +1,46 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <!-- Use a hardcoded path relative to obj because IntermediateOutputPath is not available here -->
+    <NativeBuildDir>$(MSBuildProjectDirectory)\obj\native\$(Configuration)</NativeBuildDir>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <NativeSources Include="native\**" />
+    <None Include="@(NativeSources)" />
+    <UpToDateCheckInput Include="@(NativeSources)" />
+  </ItemGroup>
+
+  <PropertyGroup Condition="$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::Linux)))">
+    <NativeLibPath>$(NativeBuildDir)/libpg.so</NativeLibPath>
+  </PropertyGroup>
+  <PropertyGroup Condition="$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::Windows)))">
+    <NativeLibPath>$(NativeBuildDir)/$(Configuration)/pg.dll</NativeLibPath>
+  </PropertyGroup>
+  <PropertyGroup Condition="$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::OSX)))">
+    <NativeLibPath>$(NativeBuildDir)/libpg.dylib</NativeLibPath>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Content Include="$(NativeLibPath)">
+      <Link>%(FileName)%(Extension)</Link>
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      <Visible>false</Visible>
+    </Content>
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="SixLabors.ImageSharp" Version="3.1.12" />
+  </ItemGroup>
+
+  <Target Name="BuildNative" BeforeTargets="BeforeBuild" Inputs="@(NativeSources)" Outputs="$(NativeLibPath)">
+    <MakeDir Directories="$(NativeBuildDir)" />
+    <Exec Command="cmake -S native -B $(NativeBuildDir) -DCMAKE_BUILD_TYPE=$(Configuration)" />
+    <Exec Command="cmake --build $(NativeBuildDir) --config $(Configuration)" />
+  </Target>
+
+</Project>

static/labs/lab14/solution/Binding/PatternGeneration/Point.cs

@@ -0,0 +1,15 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PatternGeneration
+{
+    [StructLayout(LayoutKind.Sequential)]
+    public struct Point(double x, double y)
+    {
+        public double x = x, y = y;
+    }
+}

static/labs/lab14/solution/Binding/PatternGeneration/Properties/AssemblyInfo.cs

@@ -0,0 +1 @@
+[assembly: System.Runtime.CompilerServices.DisableRuntimeMarshalling]

static/labs/lab14/solution/Binding/PatternGeneration/StripeSettings.cs

@@ -0,0 +1,18 @@
+using SixLabors.ImageSharp.PixelFormats;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PatternGeneration
+{
+    [StructLayout(LayoutKind.Sequential)]
+    public struct StripeSettings
+    {
+        public Rgb24 a, b;
+        public double stripe_a_width, stripe_b_width;
+        public double slope;
+    }
+}

static/labs/lab14/solution/Binding/PatternGeneration/native/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.10)
+project(pg C)
+
+set(CMAKE_C_STANDARD 11)
+
+include_directories(.)
+
+add_library(pg SHARED export.c)
+
+set_target_properties(pg PROPERTIES 
+    LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+)

static/labs/lab14/solution/Binding/PatternGeneration/native/color.h

@@ -0,0 +1,4 @@
+typedef struct color
+{
+    unsigned char r, g, b;
+} color_t;

static/labs/lab14/solution/Binding/PatternGeneration/native/export.c

@@ -0,0 +1,2 @@
+#define LIBRARY_EXPORT
+#include"pattern.c"