# Dokumentation ## Ziel BinaryConverter ist fuer Umgebungen gedacht, in denen eine binaere Datei nicht direkt uebertragen werden kann, Text per Copy & Paste aber moeglich ist. Die Anwendung erzeugt deshalb eine robuste Textdarstellung und prueft beim Rueckweg, ob die rekonstruierte Datei bytegenau passt. ## Dateiformat Das Transferfile besteht aus Kommentar-Metadaten, einem Beginn-Marker, Base64-Nutzdaten und einem Ende-Marker. ```text # BinaryConverter-Format: 1 # Encoding: Base64 # SourceFileNameBase64: # SourceLength: # SHA256: # CreatedUtc: # LineLength: 76 -----BEGIN BINARYCONVERTER BASE64----- -----END BINARYCONVERTER BASE64----- ``` Die Base64-Nutzdaten werden mit 76 Zeichen pro Zeile geschrieben. Das ist bewusst konservativ, damit Zeilenumbrueche in vielen Editoren, Konsolen und Remote-Sessions gut handhabbar bleiben. ## Integritaet Beim Encode wird die Eingabedatei zuerst einmal gelesen, um SHA-256 zu berechnen. Danach wird sie in einem zweiten Durchlauf als Base64 geschrieben. Der zweite Durchlauf vermeidet, dass grosse Dateien komplett in den Speicher geladen werden. Bei Encode und Decode wird zuerst in eine temporaere Datei geschrieben. Erst nach erfolgreicher Verarbeitung wird diese temporaere Datei auf den finalen Ausgabepfad verschoben beziehungsweise ersetzt. Beim Decode passiert das erst nach erfolgreicher Laengen- und SHA-256-Pruefung. Bei Fehlern wird die temporaere Datei geloescht. ## Speicherverhalten Die Anwendung arbeitet streaming-basiert: - Eingabe wird blockweise gelesen. - Base64 wird blockweise geschrieben beziehungsweise dekodiert. - Es wird nicht die komplette Eingabe- oder Ausgabedatei in den Arbeitsspeicher geladen. Beim Decode wird ein kleiner Base64-Puffer verwendet, um auch unguenstig umgebrochene Base64-Zeilen verarbeiten zu koennen. ## Fehlerverhalten Typische Fehler werden mit Exitcode `1` beendet: - Eingabedatei fehlt. - Ausgabedatei existiert bereits und `-Force` wurde nicht gesetzt. - Transferfile ist unvollstaendig, zum Beispiel fehlender Ende-Marker. - Base64-Inhalt ist ungueltig. - Dekodierte Laenge passt nicht zur Metadatenlaenge. - SHA-256 passt nicht zum Metadatenhash. Argumentfehler werden mit Exitcode `2` beendet. Erfolgreiche Ausfuehrung endet mit Exitcode `0`. ## Logging Standardmaessig schreibt BinaryConverter auf die Konsole: - Version und Operation - Eingabe- und Ausgabepfad - Fortschritt und Durchsatz - berechnete beziehungsweise gepruefte SHA-256-Summe - finale Dateigroessen Mit `-Log ` werden dieselben Informationen zusaetzlich in eine Logdatei geschrieben. ## Beispiele Datei fuer Transfer vorbereiten: ```powershell .\BinaryConverter.exe -Encode C:\temp\PowerShell.exe -Output C:\temp\Out.txt -Log C:\temp\encode.log ``` Auf dem Zielhost zurueckwandeln: ```powershell .\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Log C:\temp\decode.log ``` Bereits vorhandene Zieldatei ersetzen: ```powershell .\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Force ``` ## Repository-Struktur ```text BinaryConverter/ BinaryConverter.sln BinaryConverter/ BinaryConverter.csproj App.config Program.cs Properties/ AssemblyInfo.cs native/ Makefile README.md src/ binaryconverter.cpp .editorconfig .gitattributes .gitignore Dokumentation.md Readme.md ``` ## Native Linux-Version Unter `native/` liegt eine C++17-Implementierung fuer Linux. Sie erzeugt eine native Arch-Linux-Binary und verwendet OpenSSL/libcrypto fuer SHA-256. Das Transferformat ist identisch zur C#-Version, sodass Dateien auf Windows encoded und auf Linux decoded werden koennen oder umgekehrt. Build: ```bash cd native make ``` Die Binary liegt danach unter `native/build/binaryconverter`. ## Gitea-Hinweise Das Repository enthaelt keine Build-Artefakte. `bin/`, `obj/`, `native/build/`, Visual-Studio-Userdateien, Logs und temporaere Dateien sind ueber `.gitignore` ausgeschlossen.