From c6ac784e1ffed62a2ee65f9ddf7b28fdf60f5590 Mon Sep 17 00:00:00 2001
From: dankito <git@dankito.net>
Date: Wed, 16 Oct 2024 01:21:14 +0200
Subject: [PATCH] Added README

---
 .../examples/EpcQrCodeGeneratorExamples.kt    | 32 +++++++
 .../examples/EpcQrCodeParserExamples.kt       | 20 ++++
 README.md                                     | 92 +++++++++++++++++++
 3 files changed, 144 insertions(+)
 create mode 100644 EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeGeneratorExamples.kt
 create mode 100644 EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeParserExamples.kt
 create mode 100644 README.md

diff --git a/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeGeneratorExamples.kt b/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeGeneratorExamples.kt
new file mode 100644
index 0000000..931704f
--- /dev/null
+++ b/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeGeneratorExamples.kt
@@ -0,0 +1,32 @@
+package net.codinux.banking.epcqrcode.examples
+
+import net.codinux.banking.epcqrcode.EpcQrCodeConfig
+import net.codinux.banking.epcqrcode.ImageFormat
+
+class EpcQrCodeGeneratorExamples {
+
+    fun generateEpcQrCode() {
+        val generator = net.codinux.banking.epcqrcode.EpcQrCodeGenerator()
+
+        // these are the only two mandatory fields:
+        val receiverName = "Belgian Red Cross"
+        val iban = "BE72000000001616"
+
+        // optional but recommended fields:
+        val bic: String? = null
+        val amount: String? = "1"
+        val reference: String? = "Donation"
+        val informationForUser: String? = "Was für ein schönes EPC QR Code Beispiel" // not used / displayed by most applications
+
+        val qrCodeHeightAndWidth = 400
+        val imageFormat = ImageFormat.PNG
+
+
+        // generate EPC QR code and QR code image
+        val result = generator.generateEpcQrCode(EpcQrCodeConfig(receiverName, iban, bic, amount, reference, informationForUser,
+            qrCodeHeightAndWidth = qrCodeHeightAndWidth, imageFormat = imageFormat))
+
+        val imageBytes = result.bytes // now show these in UI
+    }
+
+}
\ No newline at end of file
diff --git a/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeParserExamples.kt b/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeParserExamples.kt
new file mode 100644
index 0000000..a285002
--- /dev/null
+++ b/EpcQrCode/src/commonTest/kotlin/net.codinux.banking.epcqrcode/examples/EpcQrCodeParserExamples.kt
@@ -0,0 +1,20 @@
+package net.codinux.banking.epcqrcode.examples
+
+class EpcQrCodeParserExamples {
+
+    fun decode() {
+        val decodedQrCodeText: String = "..." // the text that is contained / read from QR code
+
+        val parser = net.codinux.banking.epcqrcode.parser.EpcQrCodeParser()
+
+        val result = parser.parseEpcQrCode(decodedQrCodeText)
+
+        val epcQrCode = result.epcQrCode
+        if (epcQrCode != null) {
+            println("Receiver = ${epcQrCode.receiverName}, IBAN = ${epcQrCode.iban}, amount = ${epcQrCode.amount}, ...")
+        } else {
+            println("Code not decode EPC QR code: ${result.error}")
+        }
+    }
+
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59aaf54
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# EPC QR Code
+
+Vermarktet als GiroCode, scan2Code, Zahlen mit Code, ... ist der EPC QR Code ein Standard des European Payments Council 
+zum Übermitteln von Überweisungsdaten mittels eines QR Codes.
+
+Der EPC QR Code enthält Überweisungsdaten wie IBAN, Empfängername, Betrag, ...      
+Eine Clientanwendung scannt dieses QR Code und kann sofort alle Überweisungsdaten anzeigen und, sofern vom Kunden gewünscht,
+diese Überweisung direkt ausführen.
+
+## Setup
+
+### Gradle:
+
+```
+repositories {
+    // ... mavenCentral() etc.
+    maven {
+        setUrl("https://maven.dankito.net/api/packages/codinux/maven")
+    }
+}
+
+
+dependencies {
+    implementation("net.codinux.banking.epcqrcode:epc-qr-code:0.5.0")
+}
+```
+
+
+### Maven:
+
+```xml
+<repositories>
+    <repository>
+        <id>codinux</id>
+        <url>https://git.dankito.net/api/packages/codinux/maven</url>
+    </repository>
+</repositories>
+
+<dependencies>
+    <dependency>
+        <groupId>net.codinux.banking.epcqrcode</groupId>
+        <artifactId>epc-qr-code-jvm</artifactId>
+        <version>0.5.0</version>
+    </dependency>
+</dependencies>
+```
+
+## EPC QR Code erstellen
+
+```kotlin
+val generator = net.codinux.banking.epcqrcode.EpcQrCodeGenerator()
+
+// these are the only two mandatory fields:
+val receiverName = "Belgian Red Cross"
+val iban = "BE72000000001616"
+
+// optional but recommended fields:
+val bic: String? = null
+val amount: String? = "1"
+val reference: String? = "Donation"
+val informationForUser: String? = "Was für ein schönes EPC QR Code Beispiel" // not used / displayed by most applications
+
+val qrCodeHeightAndWidth = 400
+val imageFormat = ImageFormat.PNG
+
+
+// generate EPC QR code and QR code image
+val result = generator.generateEpcQrCode(EpcQrCodeConfig(receiverName, iban, bic, amount, reference, informationForUser,
+    qrCodeHeightAndWidth = qrCodeHeightAndWidth, imageFormat = imageFormat))
+
+val imageBytes = result.bytes // now show these in UI
+```
+
+## EPC QR Code dekodieren
+
+Dekodieren Sie zuerst den QR Code mittels einer QR Code Library. Den im QR Code Text übergeben Sie dann an 
+`EpcQrCodeParser` zum dekodieren der Überweisungsdaten:
+
+```kotlin
+val decodedQrCodeText: String = "..." // the text that is contained / read from QR code
+
+val parser = net.codinux.banking.epcqrcode.parser.EpcQrCodeParser()
+
+val result = parser.parseEpcQrCode(decodedQrCodeText)
+
+val epcQrCode = result.epcQrCode
+if (epcQrCode != null) {
+    println("Receiver = ${epcQrCode.receiverName}, IBAN = ${epcQrCode.iban}, amount = ${epcQrCode.amount}, ...")
+} else {
+    println("Code not decode EPC QR code: ${result.error}")
+}
+```