diff --git a/QRCoder/ASCIIQRCode.cs b/QRCoder/ASCIIQRCode.cs index 29cda3e5..fc4b94e9 100644 --- a/QRCoder/ASCIIQRCode.cs +++ b/QRCoder/ASCIIQRCode.cs @@ -5,6 +5,9 @@ namespace QRCoder { + /// + /// Represents an ASCII-style QR code generator that provides functionality to render QR codes as textual representations. + /// public class AsciiQRCode : AbstractQRCode, IDisposable { /// @@ -124,6 +127,9 @@ public string GetGraphicSmall(bool drawQuietZones = true, bool invert = false, s } + /// + /// Provides static methods for generating ASCII-style QR codes. + /// public static class AsciiQRCodeHelper { public static string GetQRCode(string plainText, int pixelsPerModule, string darkColorString, string whiteSpaceString, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, string endOfLine = "\n", bool drawQuietZones = true) diff --git a/QRCoder/AbstractQRCode.cs b/QRCoder/AbstractQRCode.cs index a123c482..e3833892 100644 --- a/QRCoder/AbstractQRCode.cs +++ b/QRCoder/AbstractQRCode.cs @@ -1,29 +1,47 @@ namespace QRCoder { + /// + /// Abstract base class for generating QR codes. + /// Derived classes typically render a QR code into a specific format (png, System.Drawing.Bitmap, PDF, etc). + /// public abstract class AbstractQRCode { + /// + /// Gets or sets the QRCodeData used to generate the QR code. + /// protected QRCodeData QrCodeData { get; set; } + /// + /// Initializes a new instance of the AbstractQRCode class. + /// protected AbstractQRCode() { this.QrCodeData = null!; } + /// + /// Initializes a new instance of the AbstractQRCode class with the specified QRCodeData. + /// + /// The QRCodeData object generated by QRCodeGenerator.CreateQrCode(). protected AbstractQRCode(QRCodeData data) { this.QrCodeData = data; } /// - /// Set a QRCodeData object that will be used to generate QR code. Used in COM Objects connections + /// Sets the QRCodeData object that will be used to generate the QR code. + /// This method is useful for COM objects connections. /// - /// Need a QRCodeData object generated by QRCodeGenerator.CreateQrCode() + /// The QRCodeData object generated by QRCodeGenerator.CreateQrCode(). virtual public void SetQRCodeData(QRCodeData data) { this.QrCodeData = data; } + /// + /// Disposes the QRCodeData object. + /// public void Dispose() { this.QrCodeData?.Dispose(); this.QrCodeData = null!; } } -} \ No newline at end of file +} diff --git a/QRCoder/ArtQRCode.cs b/QRCoder/ArtQRCode.cs index b80f5178..fff7840c 100644 --- a/QRCoder/ArtQRCode.cs +++ b/QRCoder/ArtQRCode.cs @@ -9,20 +9,24 @@ // pull request raised to extend library used. namespace QRCoder { + /// + /// Represents an art-style QR code generator that provides functionality to render QR codes with dots as modules. + /// #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif public class ArtQRCode : AbstractQRCode, IDisposable { /// + /// Initializes a new instance of the class. /// Constructor without params to be used in COM Objects connections /// public ArtQRCode() { } /// - /// Creates new ArtQrCode object + /// Initializes a new instance of the class with the specified . /// - /// QRCodeData generated by the QRCodeGenerator + /// generated by the . public ArtQRCode(QRCodeData data) : base(data) { } /// @@ -256,6 +260,9 @@ public enum BackgroundImageStyle } } + /// + /// Provides static methods for creating art-style QR codes. + /// #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif diff --git a/QRCoder/Base64QRCode.cs b/QRCoder/Base64QRCode.cs index bba6e9bc..799be2b7 100644 --- a/QRCoder/Base64QRCode.cs +++ b/QRCoder/Base64QRCode.cs @@ -9,28 +9,58 @@ namespace QRCoder { + /// + /// Represents a QR code generator that outputs base64-encoded images. + /// public class Base64QRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public Base64QRCode() { } + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public Base64QRCode(QRCodeData data) : base(data) { } + /// + /// Returns a base64-encoded string that contains the resulting QR code as a PNG image. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a base64-encoded string. public string GetGraphic(int pixelsPerModule) { return this.GetGraphic(pixelsPerModule, Color.Black, Color.White, true); } - + /// + /// Returns a base64-encoded string that contains the resulting QR code as an image. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// Indicates if quiet zones around the QR code should be drawn. + /// The type of image to generate (PNG, JPEG, GIF). + /// Returns the QR code graphic as a base64-encoded string. public string GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, bool drawQuietZones = true, ImageType imgType = ImageType.Png) { return this.GetGraphic(pixelsPerModule, ColorTranslator.FromHtml(darkColorHtmlHex), ColorTranslator.FromHtml(lightColorHtmlHex), drawQuietZones, imgType); } + /// + /// Returns a base64-encoded string that contains the resulting QR code as an image. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// Indicates if quiet zones around the QR code should be drawn. + /// The type of image to generate (PNG, JPEG, GIF). + /// Returns the QR code graphic as a base64-encoded string. public string GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, bool drawQuietZones = true, ImageType imgType = ImageType.Png) { if (imgType == ImageType.Png) @@ -78,6 +108,18 @@ public string GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, } #if SYSTEM_DRAWING + /// + /// Returns a base64-encoded string that contains the resulting QR code as an image with an embedded icon. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// The icon to embed in the center of the QR code. + /// The size of the icon as a percentage of the QR code. + /// The width of the border around the icon. + /// Indicates if quiet zones around the QR code should be drawn. + /// The type of image to generate (PNG, JPEG, GIF). + /// Returns the QR code graphic as a base64-encoded string. #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif @@ -94,6 +136,12 @@ public string GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, #endif #if SYSTEM_DRAWING + /// + /// Converts a bitmap to a base64-encoded string. + /// + /// The bitmap to convert. + /// The type of image (PNG, JPEG, GIF). + /// Returns the base64-encoded string representation of the bitmap. #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif @@ -124,23 +172,53 @@ private string BitmapToBase64(Bitmap bmp, ImageType imgType) } #endif + /// + /// Specifies the type of image to generate. + /// public enum ImageType { #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif + /// + /// GIF image format. + /// Gif, #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif + /// + /// JPEG image format. + /// Jpeg, + /// + /// PNG image format. + /// Png } } + /// + /// Provides static methods for creating base64-encoded QR codes. + /// public static class Base64QRCodeHelper { + /// + /// Creates a base64-encoded QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Indicates if quiet zones around the QR code should be drawn. + /// The type of image to generate (PNG, JPEG, GIF). + /// Returns the QR code graphic as a base64-encoded string. public static string GetQRCode(string plainText, int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, bool drawQuietZones = true, ImageType imgType = ImageType.Png) { using (var qrGenerator = new QRCodeGenerator()) @@ -151,4 +229,4 @@ public static string GetQRCode(string plainText, int pixelsPerModule, string dar } } -#endif \ No newline at end of file +#endif diff --git a/QRCoder/BitmapByteQRCode.cs b/QRCoder/BitmapByteQRCode.cs index 9a1ab67d..feecdd9a 100644 --- a/QRCoder/BitmapByteQRCode.cs +++ b/QRCoder/BitmapByteQRCode.cs @@ -6,26 +6,53 @@ namespace QRCoder { + /// + /// Represents a QR code generator that outputs QR codes as bitmap byte arrays. + /// // ReSharper disable once InconsistentNaming public class BitmapByteQRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public BitmapByteQRCode() { } + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public BitmapByteQRCode(QRCodeData data) : base(data) { } + /// + /// Returns the QR code graphic as a bitmap byte array. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a bitmap byte array. public byte[] GetGraphic(int pixelsPerModule) { return GetGraphic(pixelsPerModule, new byte[] { 0x00, 0x00, 0x00 }, new byte[] { 0xFF, 0xFF, 0xFF }); } + /// + /// Returns the QR code graphic as a bitmap byte array. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// Returns the QR code graphic as a bitmap byte array. public byte[] GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex) { return GetGraphic(pixelsPerModule, HexColorToByteArray(darkColorHtmlHex), HexColorToByteArray(lightColorHtmlHex)); } + /// + /// Returns the QR code graphic as a bitmap byte array. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules as an RGB byte array. + /// The color of the light modules as an RGB byte array. + /// Returns the QR code graphic as a bitmap byte array. public byte[] GetGraphic(int pixelsPerModule, byte[] darkColorRgb, byte[] lightColorRgb) { var sideLength = this.QrCodeData.ModuleMatrix.Count * pixelsPerModule; @@ -76,16 +103,26 @@ public byte[] GetGraphic(int pixelsPerModule, byte[] darkColorRgb, byte[] lightC return bmp.ToArray(); } + /// + /// Converts a hex color string to a byte array. + /// + /// The hex color string to convert. + /// Returns the color as a byte array. private byte[] HexColorToByteArray(string colorString) { if (colorString.StartsWith("#")) colorString = colorString.Substring(1); byte[] byteColor = new byte[colorString.Length / 2]; for (int i = 0; i < byteColor.Length; i++) - byteColor[i] = byte.Parse(colorString.Substring(i * 2, 2), System.Globalization.NumberStyles.HexNumber, System.Globalization.CultureInfo.InvariantCulture); + byteColor[i] = byte.Parse(colorString.Substring(i * 2, 2), System.Globalization.NumberStyles.HexNumber, System.Globalization.CultureInfo.InvariantCulture); return byteColor; } + /// + /// Converts an integer to a 4-byte array. + /// + /// The integer to convert. + /// Returns the integer as a 4-byte array. private byte[] IntTo4Byte(int inp) { byte[] bytes = new byte[2]; @@ -99,8 +136,24 @@ private byte[] IntTo4Byte(int inp) } + /// + /// Provides helper functions for creating bitmap byte array QR codes. + /// public static class BitmapByteQRCodeHelper { + /// + /// Creates a bitmap byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Returns the QR code graphic as a bitmap byte array. public static byte[] GetQRCode(string plainText, int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1) @@ -113,6 +166,13 @@ public static byte[] GetQRCode(string plainText, int pixelsPerModule, string dar return qrCode.GetGraphic(pixelsPerModule, darkColorHtmlHex, lightColorHtmlHex); } + /// + /// Creates a bitmap byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The level of error correction data. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a bitmap byte array. public static byte[] GetQRCode(string txt, QRCodeGenerator.ECCLevel eccLevel, int size) { using (var qrGen = new QRCodeGenerator()) diff --git a/QRCoder/Exceptions/DataTooLongException.cs b/QRCoder/Exceptions/DataTooLongException.cs index bb7fbe25..04608257 100644 --- a/QRCoder/Exceptions/DataTooLongException.cs +++ b/QRCoder/Exceptions/DataTooLongException.cs @@ -2,14 +2,30 @@ namespace QRCoder.Exceptions { + /// + /// Exception thrown when the given payload exceeds the maximum size of the QR code standard. + /// public class DataTooLongException : Exception { + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The error correction level of the QR code. + /// The encoding mode of the QR code. + /// The maximum size allowed for the given parameters in bytes. public DataTooLongException(string eccLevel, string encodingMode, int maxSizeByte) : base( - $"The given payload exceeds the maximum size of the QR code standard. The maximum size allowed for the choosen paramters (ECC level={eccLevel}, EncodingMode={encodingMode}) is {maxSizeByte} byte." + $"The given payload exceeds the maximum size of the QR code standard. The maximum size allowed for the chosen parameters (ECC level={eccLevel}, EncodingMode={encodingMode}) is {maxSizeByte} bytes." ){} + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The error correction level of the QR code. + /// The encoding mode of the QR code. + /// The fixed version of the QR code. + /// The maximum size allowed for the given parameters in bytes. public DataTooLongException(string eccLevel, string encodingMode, int version, int maxSizeByte) : base( - $"The given payload exceeds the maximum size of the QR code standard. The maximum size allowed for the choosen paramters (ECC level={eccLevel}, EncodingMode={encodingMode}, FixedVersion={version}) is {maxSizeByte} byte." + $"The given payload exceeds the maximum size of the QR code standard. The maximum size allowed for the chosen parameters (ECC level={eccLevel}, EncodingMode={encodingMode}, FixedVersion={version}) is {maxSizeByte} bytes." ) { } } diff --git a/QRCoder/Extensions/StringValueAttribute.cs b/QRCoder/Extensions/StringValueAttribute.cs index 461b8131..1bdcd46e 100644 --- a/QRCoder/Extensions/StringValueAttribute.cs +++ b/QRCoder/Extensions/StringValueAttribute.cs @@ -33,14 +33,15 @@ public StringValueAttribute(string value) } } + /// + /// Enumeration extension methods. + /// [Obsolete("This class will be removed in a future version of QRCoder.")] public static class CustomExtensions { /// /// Will get the string value for a given enum's value /// - /// - /// #if NET6_0_OR_GREATER [RequiresUnreferencedCode("This method uses reflection to examine the provided enum value.")] #endif diff --git a/QRCoder/PayloadGenerator.cs b/QRCoder/PayloadGenerator.cs index 5a253daf..33e54614 100644 --- a/QRCoder/PayloadGenerator.cs +++ b/QRCoder/PayloadGenerator.cs @@ -11,8 +11,16 @@ namespace QRCoder { + /// + /// Provides utility methods for generating QR code payloads. + /// public static partial class PayloadGenerator { + /// + /// Validates the structure and checksum of an IBAN. + /// + /// The IBAN to validate. + /// True if the IBAN is valid; otherwise, false. private static bool IsValidIban(string iban) { //Clean IBAN @@ -37,6 +45,11 @@ private static bool IsValidIban(string iban) return structurallyValid && checksumValid; } + /// + /// Validates the structure and checksum of a QR IBAN. + /// + /// The QR IBAN to validate. + /// True if the QR IBAN is valid; otherwise, false. private static bool IsValidQRIban(string iban) { var foundQrIid = false; @@ -49,12 +62,23 @@ private static bool IsValidQRIban(string iban) return IsValidIban(iban) && foundQrIid; } + /// + /// Validates the structure of a BIC. + /// + /// The BIC to validate. + /// True if the BIC is valid; otherwise, false. private static bool IsValidBic(string bic) { return Regex.IsMatch(bic.Replace(" ", ""), @"^([a-zA-Z]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3})?)$"); } + /// + /// Converts a string to a specified encoding. + /// + /// The string to convert. + /// The encoding to use. + /// The converted string. private static string ConvertStringToEncoding(string message, string encoding) { Encoding iso = Encoding.GetEncoding(encoding); @@ -64,6 +88,12 @@ private static string ConvertStringToEncoding(string message, string encoding) return iso.GetString(isoBytes); } + /// + /// Escapes forbidden characters in a string. + /// + /// The input string. + /// Indicates whether to use a simple escape mode. + /// The escaped string. private static string EscapeInput(string inp, bool simple = false) { char[] forbiddenChars = {'\\', ';', ',', ':'}; @@ -80,9 +110,14 @@ private static string EscapeInput(string inp, bool simple = false) + /// + /// Validates a string using the Mod10 checksum algorithm. + /// + /// The string to validate. + /// True if the string is valid; otherwise, false. public static bool ChecksumMod10(string digits) { - if (string.IsNullOrEmpty(digits) || digits.Length < 2) + if (string.IsNullOrEmpty(digits) || digits.Length < 2) return false; int[] mods = new int[] { 0, 9, 4, 6, 8, 2, 7, 1, 3, 5 }; @@ -94,8 +129,13 @@ public static bool ChecksumMod10(string digits) } var checksum = (10 - remainder) % 10; return checksum == Convert.ToInt32(digits[digits.Length - 1]) - 48; - } + } + /// + /// Checks if a string is in hexadecimal format. + /// + /// The input string. + /// True if the string is in hexadecimal format; otherwise, false. private static bool isHexStyle(string inp) { return (System.Text.RegularExpressions.Regex.IsMatch(inp, @"\A\b[0-9a-fA-F]+\b\Z") || System.Text.RegularExpressions.Regex.IsMatch(inp, @"\A\b(0[xX])?[0-9a-fA-F]+\b\Z")); diff --git a/QRCoder/PayloadGenerator/BezahlCode.cs b/QRCoder/PayloadGenerator/BezahlCode.cs index 4d47cec7..486b1671 100644 --- a/QRCoder/PayloadGenerator/BezahlCode.cs +++ b/QRCoder/PayloadGenerator/BezahlCode.cs @@ -5,6 +5,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Represents a BezahlCode payload for QR codes. + /// public class BezahlCode : Payload { //BezahlCode specification: http://www.bezahlcode.de/wp-content/uploads/BezahlCode_TechDok.pdf @@ -19,7 +22,7 @@ public class BezahlCode : Payload /// - /// Constructor for contact data + /// Initializes a new instance of the class for contact data. /// /// Type of the bank transfer /// Name of the receiver (Empfänger) @@ -34,7 +37,7 @@ public BezahlCode(AuthorityType authority, string name, string account = "", str /// - /// Constructor for non-SEPA payments + /// Initializes a new instance of the class for non-SEPA payments. /// /// Type of the bank transfer /// Name of the receiver (Empfänger) @@ -54,7 +57,7 @@ public BezahlCode(AuthorityType authority, string name, string account, string b } /// - /// Constructor for SEPA payments + /// Initializes a new instance of the class for SEPA payments. /// /// Type of the bank transfer /// Name of the receiver (Empfänger) @@ -81,7 +84,7 @@ public BezahlCode(AuthorityType authority, string name, string iban, string bic, /// - /// Generic constructor. Please use specific (non-SEPA or SEPA) constructor + /// Generic constructor. Please use specific (non-SEPA or SEPA) constructor. /// /// Type of the bank transfer /// Name of the receiver (Empfänger) @@ -239,6 +242,7 @@ public BezahlCode(AuthorityType authority, string name, string account, string b } + /// public override string ToString() { var bezahlCodePayload = $"bank://{authority}?"; @@ -550,17 +554,32 @@ public enum AuthorityType contact_v2 } + /// + /// Exception class for BezahlCode errors. + /// public class BezahlCodeException : Exception { + /// + /// Initializes a new instance of the class. + /// public BezahlCodeException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public BezahlCodeException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The message that describes the error. + /// The exception that is the cause of the current exception. public BezahlCodeException(string message, Exception inner) : base(message, inner) { diff --git a/QRCoder/PayloadGenerator/BitcoinAddress.cs b/QRCoder/PayloadGenerator/BitcoinAddress.cs index 94361e13..74f701a1 100644 --- a/QRCoder/PayloadGenerator/BitcoinAddress.cs +++ b/QRCoder/PayloadGenerator/BitcoinAddress.cs @@ -2,8 +2,19 @@ { public static partial class PayloadGenerator { + /// + /// Generates a payload for Bitcoin payment addresses. + /// public class BitcoinAddress : BitcoinLikeCryptoCurrencyAddress { + /// + /// Initializes a new instance of the class. + /// Generates a Bitcoin payment payload. QR Codes with this payload can open a payment app. + /// + /// The Bitcoin address of the payment receiver. + /// The amount of Bitcoin to transfer. + /// A reference label. + /// A reference text or message. public BitcoinAddress(string address, double? amount, string? label = null, string? message = null) : base(BitcoinLikeCryptoCurrencyType.Bitcoin, address, amount, label, message) { } } diff --git a/QRCoder/PayloadGenerator/BitcoinCashAddress.cs b/QRCoder/PayloadGenerator/BitcoinCashAddress.cs index 32293491..e2411cfb 100644 --- a/QRCoder/PayloadGenerator/BitcoinCashAddress.cs +++ b/QRCoder/PayloadGenerator/BitcoinCashAddress.cs @@ -2,8 +2,19 @@ { public static partial class PayloadGenerator { + /// + /// Generates a payload for Bitcoin Cash payment addresses. + /// public class BitcoinCashAddress : BitcoinLikeCryptoCurrencyAddress { + /// + /// Initializes a new instance of the class. + /// Generates a Bitcoin Cash payment payload. QR Codes with this payload can open a payment app. + /// + /// The Bitcoin Cash address of the payment receiver. + /// The amount of Bitcoin Cash to transfer. + /// A reference label. + /// A reference text or message. public BitcoinCashAddress(string address, double? amount, string? label = null, string? message = null) : base(BitcoinLikeCryptoCurrencyType.BitcoinCash, address, amount, label, message) { } } diff --git a/QRCoder/PayloadGenerator/BitcoinLikeCryptoCurrencyAddress.cs b/QRCoder/PayloadGenerator/BitcoinLikeCryptoCurrencyAddress.cs index 8ca46a4a..62853670 100644 --- a/QRCoder/PayloadGenerator/BitcoinLikeCryptoCurrencyAddress.cs +++ b/QRCoder/PayloadGenerator/BitcoinLikeCryptoCurrencyAddress.cs @@ -7,6 +7,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a payload for Bitcoin-like cryptocurrency payment addresses. + /// public class BitcoinLikeCryptoCurrencyAddress : Payload { private readonly BitcoinLikeCryptoCurrencyType currencyType; @@ -15,13 +18,14 @@ public class BitcoinLikeCryptoCurrencyAddress : Payload private readonly double? amount; /// - /// Generates a Bitcoin like cryptocurrency payment payload. QR Codes with this payload can open a payment app. + /// Initializes a new instance of the class. + /// Generates a Bitcoin-like cryptocurrency payment payload. QR Codes with this payload can open a payment app. /// - /// Bitcoin like cryptocurrency address of the payment receiver - /// Bitcoin like cryptocurrency address of the payment receiver - /// Amount of coins to transfer - /// Reference label - /// Referece text aka message + /// The type of Bitcoin-like cryptocurrency. + /// The cryptocurrency address of the payment receiver. + /// The amount of coins to transfer. + /// A reference label. + /// A reference text or message. public BitcoinLikeCryptoCurrencyAddress(BitcoinLikeCryptoCurrencyType currencyType, string address, double? amount, string? label = null, string? message = null) { this.currencyType = currencyType; @@ -40,6 +44,10 @@ public BitcoinLikeCryptoCurrencyAddress(BitcoinLikeCryptoCurrencyType currencyTy this.amount = amount; } + /// + /// Returns a string representation of the Bitcoin-like cryptocurrency address payload. + /// + /// A string representation of the cryptocurrency address payload. public override string ToString() { string? query = null; @@ -61,10 +69,24 @@ public override string ToString() return $"{Enum.GetName(typeof(BitcoinLikeCryptoCurrencyType), currencyType)!.ToLower()}:{address}{query}"; } + /// + /// Enumerates Bitcoin-like cryptocurrencies. + /// public enum BitcoinLikeCryptoCurrencyType { + /// + /// Bitcoin. + /// Bitcoin, + + /// + /// Bitcoin Cash. + /// BitcoinCash, + + /// + /// Litecoin. + /// Litecoin } } diff --git a/QRCoder/PayloadGenerator/Bookmark.cs b/QRCoder/PayloadGenerator/Bookmark.cs index 720866d1..cc3c4413 100644 --- a/QRCoder/PayloadGenerator/Bookmark.cs +++ b/QRCoder/PayloadGenerator/Bookmark.cs @@ -2,21 +2,28 @@ { public static partial class PayloadGenerator { + /// + /// Generates a bookmark payload. When scanned by a QR code reader, this creates a browser bookmark. + /// public class Bookmark : Payload { private readonly string url, title; /// - /// Generates a bookmark payload. Scanned by an QR Code reader, this one creates a browser bookmark. + /// Initializes a new instance of the class. /// - /// Url of the bookmark - /// Title of the bookmark + /// The URL of the bookmark. + /// The title of the bookmark. public Bookmark(string url, string title) { this.url = EscapeInput(url); this.title = EscapeInput(title); } + /// + /// Returns a string representation of the bookmark payload. + /// + /// A string representation of the bookmark payload in the MEBKM format. public override string ToString() { return $"MEBKM:TITLE:{this.title};URL:{this.url};;"; diff --git a/QRCoder/PayloadGenerator/CalendarEvent.cs b/QRCoder/PayloadGenerator/CalendarEvent.cs index f0cf9507..b6d22f9a 100644 --- a/QRCoder/PayloadGenerator/CalendarEvent.cs +++ b/QRCoder/PayloadGenerator/CalendarEvent.cs @@ -4,6 +4,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a calendar entry/event payload. + /// public class CalendarEvent : Payload { private readonly string subject, start, end; @@ -11,29 +14,29 @@ public class CalendarEvent : Payload private readonly EventEncoding encoding; /// - /// Generates a calender entry/event payload. + /// Initializes a new instance of the class. /// - /// Subject/title of the calender event - /// Description of the event - /// Location (lat:long or address) of the event - /// Start time (incl. UTC offset) of the event - /// End time (incl. UTC offset) of the event - /// Is it a full day event? - /// Type of encoding (universal or iCal) + /// Subject/title of the calendar event. + /// Description of the event. + /// Location (latitude:longitude or address) of the event. + /// Start time (including UTC offset) of the event. + /// End time (including UTC offset) of the event. + /// Indicates if it is a full day event. + /// Type of encoding (universal or iCal). public CalendarEvent(string subject, string? description, string? location, DateTimeOffset start, DateTimeOffset end, bool allDayEvent, EventEncoding encoding = EventEncoding.Universal) : this(subject, description, location, start.UtcDateTime, end.UtcDateTime, allDayEvent, encoding) { } /// - /// Generates a calender entry/event payload. + /// Initializes a new instance of the class. /// - /// Subject/title of the calender event - /// Description of the event - /// Location (lat:long or address) of the event - /// Start time of the event - /// End time of the event - /// Is it a full day event? - /// Type of encoding (universal or iCal) + /// Subject/title of the calendar event. + /// Description of the event. + /// Location (latitude:longitude or address) of the event. + /// Start time of the event. + /// End time of the event. + /// Indicates if it is a full day event. + /// Type of encoding (universal or iCal). public CalendarEvent(string subject, string? description, string? location, DateTime start, DateTime end, bool allDayEvent, EventEncoding encoding = EventEncoding.Universal) { this.subject = subject; @@ -48,11 +51,15 @@ public CalendarEvent(string subject, string? description, string? location, Date dtFormatStart = "yyyyMMddTHHmmssZ"; if (end.Kind == DateTimeKind.Utc) dtFormatEnd = "yyyyMMddTHHmmssZ"; - } + } this.start = start.ToString(dtFormatStart); this.end = end.ToString(dtFormatEnd); } + /// + /// Returns a string representation of the calendar event payload. + /// + /// A string representation of the calendar event in the VEVENT format. public override string ToString() { var vEvent = $"BEGIN:VEVENT{Environment.NewLine}"; @@ -69,9 +76,19 @@ public override string ToString() return vEvent; } + /// + /// Specifies the encoding type for the calendar event. + /// public enum EventEncoding { + /// + /// iCalendar complete encoding. + /// iCalComplete, + + /// + /// Universal encoding. + /// Universal } } diff --git a/QRCoder/PayloadGenerator/ContactData.cs b/QRCoder/PayloadGenerator/ContactData.cs index e7d054b7..d6fdfbdf 100644 --- a/QRCoder/PayloadGenerator/ContactData.cs +++ b/QRCoder/PayloadGenerator/ContactData.cs @@ -4,6 +4,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a vCard or meCard contact dataset. + /// public class ContactData : Payload { private readonly string firstname; @@ -29,28 +32,28 @@ public class ContactData : Payload /// - /// Generates a vCard or meCard contact dataset + /// Initializes a new instance of the class. /// - /// Payload output type - /// The firstname - /// The lastname - /// The displayname - /// Normal phone number - /// Mobile phone - /// Office phone number - /// E-Mail address - /// Birthday - /// Website / Homepage - /// Street - /// Housenumber - /// City - /// State or Region - /// Zip code - /// Country - /// The address order format to use - /// Memo text / notes - /// Organisation/Company - /// Organisation/Company Title + /// Payload output type. + /// The first name. + /// The last name. + /// The display name. + /// Normal phone number. + /// Mobile phone. + /// Office phone number. + /// E-Mail address. + /// Birthday. + /// Website / Homepage. + /// Street. + /// House number. + /// City. + /// State or Region. + /// Zip code. + /// Country. + /// The address order format to use. + /// Memo text / notes. + /// Organization/Company. + /// Organization/Company Title. public ContactData(ContactOutputType outputType, string firstname, string lastname, string? nickname = null, string? phone = null, string? mobilePhone = null, string? workPhone = null, string? email = null, DateTime? birthday = null, string? website = null, string? street = null, string? houseNumber = null, string? city = null, string? zipCode = null, string? country = null, string? note = null, string? stateRegion = null, AddressOrder addressOrder = AddressOrder.Default, string? org = null, string? orgTitle = null) { this.firstname = firstname; @@ -75,6 +78,10 @@ public ContactData(ContactOutputType outputType, string firstname, string lastna this.outputType = outputType; } + /// + /// Returns a string representation of the contact data payload. + /// + /// A string representation of the contact data in the specified format. public override string ToString() { string payload = string.Empty; @@ -192,7 +199,7 @@ public override string ToString() addressString = $";;{(!string.IsNullOrEmpty(houseNumber) ? houseNumber + " " : "")}{(!string.IsNullOrEmpty(street) ? street : "")};{(!string.IsNullOrEmpty(city) ? city : "")};{(!string.IsNullOrEmpty(stateRegion) ? stateRegion : "")};{(!string.IsNullOrEmpty(zipCode) ? zipCode : "")};{(!string.IsNullOrEmpty(country) ? country : "")}\r\n"; } payload += addressString; - + if (birthday != null) payload += $"BDAY:{((DateTime)birthday).ToString("yyyyMMdd")}\r\n"; if (!string.IsNullOrEmpty(website)) @@ -215,21 +222,43 @@ public override string ToString() /// public enum ContactOutputType { + /// + /// MeCard output type. + /// MeCard, + + /// + /// vCard 2.1 output type. + /// VCard21, + + /// + /// vCard 3.0 output type. + /// VCard3, + + /// + /// vCard 4.0 output type. + /// VCard4 } /// - /// define the address format - /// Default: European format, ([Street] [House Number] and [Postal Code] [City] + /// Define the address format. + /// Default: European format, ([Street] [House Number] and [Postal Code] [City]) /// Reversed: North American and others format ([House Number] [Street] and [City] [Postal Code]) /// public enum AddressOrder { + /// + /// Default address order format (European format). + /// Default, + + /// + /// Reversed address order format (North American and others format). + /// Reversed } } diff --git a/QRCoder/PayloadGenerator/Geolocation.cs b/QRCoder/PayloadGenerator/Geolocation.cs index 65b546d0..23627725 100644 --- a/QRCoder/PayloadGenerator/Geolocation.cs +++ b/QRCoder/PayloadGenerator/Geolocation.cs @@ -2,24 +2,32 @@ { public static partial class PayloadGenerator { + /// + /// Generates a geo location payload. Supports raw location (GEO encoding) or Google Maps link (GoogleMaps encoding). + /// public class Geolocation : Payload { private readonly string latitude, longitude; private readonly GeolocationEncoding encoding; /// - /// Generates a geo location payload. Supports raw location (GEO encoding) or Google Maps link (GoogleMaps encoding) + /// Initializes a new instance of the class. + /// Supports raw location (GEO encoding) or Google Maps link (GoogleMaps encoding). /// - /// Latitude with . as splitter - /// Longitude with . as splitter - /// Encoding type - GEO or GoogleMaps + /// Latitude with . as splitter. + /// Longitude with . as splitter. + /// Encoding type - GEO or GoogleMaps. public Geolocation(string latitude, string longitude, GeolocationEncoding encoding = GeolocationEncoding.GEO) { - this.latitude = latitude.Replace(",","."); + this.latitude = latitude.Replace(",", "."); this.longitude = longitude.Replace(",", "."); this.encoding = encoding; } + /// + /// Returns a string representation of the geolocation payload. + /// + /// A string representation of the geolocation payload in the specified encoding format. public override string ToString() { switch (this.encoding) @@ -33,9 +41,19 @@ public override string ToString() } } + /// + /// Defines the encoding types for geolocation payloads. + /// public enum GeolocationEncoding { + /// + /// GEO encoding type. + /// GEO, + + /// + /// Google Maps encoding type. + /// GoogleMaps } } diff --git a/QRCoder/PayloadGenerator/Girocode.cs b/QRCoder/PayloadGenerator/Girocode.cs index 8fa99952..0cf5f54c 100644 --- a/QRCoder/PayloadGenerator/Girocode.cs +++ b/QRCoder/PayloadGenerator/Girocode.cs @@ -4,6 +4,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates the payload for a Girocode (QR-Code with credit transfer information). + /// public class Girocode : Payload { //Keep in mind, that the ECC level has to be set to "M" when generating a Girocode! @@ -16,23 +19,25 @@ public class Girocode : Payload private readonly GirocodeEncoding encoding; private readonly TypeOfRemittance typeOfRemittance; + /// + /// Gets the ECC level required for Girocode, which is always set to M. + /// public override QRCodeGenerator.ECCLevel EccLevel { get { return QRCodeGenerator.ECCLevel.M; } } /// - /// Generates the payload for a Girocode (QR-Code with credit transfer information). - /// Attention: When using Girocode payload, QR code must be generated with ECC level M! + /// Initializes a new instance of the class, which contains a payload for a Girocode (QR-Code with credit transfer information). /// /// Account number of the Beneficiary. Only IBAN is allowed. /// BIC of the Beneficiary Bank. /// Name of the Beneficiary. - /// Amount of the Credit Transfer in Euro. - /// (Amount must be more than 0.01 and less than 999999999.99) + /// Amount of the Credit Transfer in Euro. (Amount must be more than 0.01 and less than 999999999.99) /// Remittance Information (Purpose-/reference text). (optional) /// Type of remittance information. Either structured (e.g. ISO 11649 RF Creditor Reference) and max. 35 chars or unstructured and max. 140 chars. /// Purpose of the Credit Transfer (optional) /// Beneficiary to originator information. (optional) /// Girocode version. Either 001 or 002. Default: 001. /// Encoding of the Girocode payload. Default: ISO-8859-1 + /// Thrown when the input values are not valid according to the Girocode specification. public Girocode(string iban, string bic, string name, decimal amount, string remittanceInformation = "", TypeOfRemittance typeOfRemittance = TypeOfRemittance.Unstructured, string purposeOfCreditTransfer = "", string messageToGirocodeUser = "", GirocodeVersion version = GirocodeVersion.Version1, GirocodeEncoding encoding = GirocodeEncoding.ISO_8859_1) { this.version = version; @@ -49,22 +54,26 @@ public Girocode(string iban, string bic, string name, decimal amount, string rem if (amount.ToString().Replace(",", ".").Contains(".") && amount.ToString().Replace(",",".").Split('.')[1].TrimEnd('0').Length > 2) throw new GirocodeException("Amount must have less than 3 digits after decimal point."); if (amount < 0.01m || amount > 999999999.99m) - throw new GirocodeException("Amount has to at least 0.01 and must be smaller or equal to 999999999.99."); + throw new GirocodeException("Amount has to be at least 0.01 and must be smaller or equal to 999999999.99."); this.amount = amount; if (purposeOfCreditTransfer.Length > 4) throw new GirocodeException("Purpose of credit transfer can only have 4 chars at maximum."); this.purposeOfCreditTransfer = purposeOfCreditTransfer; if (typeOfRemittance == TypeOfRemittance.Unstructured && remittanceInformation.Length > 140) - throw new GirocodeException("Unstructured reference texts have to shorter than 141 chars."); + throw new GirocodeException("Unstructured reference texts have to be shorter than 141 chars."); if (typeOfRemittance == TypeOfRemittance.Structured && remittanceInformation.Length > 35) - throw new GirocodeException("Structured reference texts have to shorter than 36 chars."); + throw new GirocodeException("Structured reference texts have to be shorter than 36 chars."); this.typeOfRemittance = typeOfRemittance; this.remittanceInformation = remittanceInformation; if (messageToGirocodeUser.Length > 70) - throw new GirocodeException("Message to the Girocode-User reader texts have to shorter than 71 chars."); + throw new GirocodeException("Message to the Girocode-User reader texts have to be shorter than 71 chars."); this.messageToGirocodeUser = messageToGirocodeUser; } + /// + /// Returns the Girocode payload as a string. + /// + /// The Girocode payload as a string. public override string ToString() { var girocodePayload = "BCD" + br; @@ -87,41 +96,110 @@ public override string ToString() return ConvertStringToEncoding(girocodePayload, encoding.ToString().Replace("_","-")); } + /// + /// Defines the Girocode version. + /// public enum GirocodeVersion { + /// + /// Girocode version 1. + /// Version1, + + /// + /// Girocode version 2. + /// Version2 } + /// + /// Defines the type of remittance information. + /// public enum TypeOfRemittance { + /// + /// Structured remittance information. + /// Structured, + + /// + /// Unstructured remittance information. + /// Unstructured } + /// + /// Defines the encoding types for Girocode payloads. + /// public enum GirocodeEncoding { + /// + /// UTF-8 encoding. + /// UTF_8, + + /// + /// ISO-8859-1 encoding. + /// ISO_8859_1, + + /// + /// ISO-8859-2 encoding. + /// ISO_8859_2, + + /// + /// ISO-8859-4 encoding. + /// ISO_8859_4, + + /// + /// ISO-8859-5 encoding. + /// ISO_8859_5, + + /// + /// ISO-8859-7 encoding. + /// ISO_8859_7, + + /// + /// ISO-8859-10 encoding. + /// ISO_8859_10, + + /// + /// ISO-8859-15 encoding. + /// ISO_8859_15 } + /// + /// Represents errors that occur during Girocode generation. + /// public class GirocodeException : Exception { + /// + /// Initializes a new instance of the class. + /// public GirocodeException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public GirocodeException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception, or a null reference if no inner exception is specified. public GirocodeException(string message, Exception inner) : base(message, inner) { diff --git a/QRCoder/PayloadGenerator/LitecoinAddress.cs b/QRCoder/PayloadGenerator/LitecoinAddress.cs index d403d319..b7d0bfe5 100644 --- a/QRCoder/PayloadGenerator/LitecoinAddress.cs +++ b/QRCoder/PayloadGenerator/LitecoinAddress.cs @@ -2,8 +2,19 @@ { public static partial class PayloadGenerator { + /// + /// Generates a payload for Litecoin payment addresses. + /// public class LitecoinAddress : BitcoinLikeCryptoCurrencyAddress { + /// + /// Initializes a new instance of the class. + /// Generates a Litecoin payment payload. QR Codes with this payload can open a payment app. + /// + /// The Litecoin address of the payment receiver. + /// The amount of Litecoin to transfer. + /// A reference label. + /// A reference text or message. public LitecoinAddress(string address, double? amount, string? label = null, string? message = null) : base(BitcoinLikeCryptoCurrencyType.Litecoin, address, amount, label, message) { } } diff --git a/QRCoder/PayloadGenerator/MMS.cs b/QRCoder/PayloadGenerator/MMS.cs index bb342800..f3b33321 100644 --- a/QRCoder/PayloadGenerator/MMS.cs +++ b/QRCoder/PayloadGenerator/MMS.cs @@ -4,16 +4,19 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a MMS (Multimedia Messaging Service) payload for QR codes. + /// public class MMS : Payload { private readonly string number, subject; private readonly MMSEncoding encoding; /// - /// Creates a MMS payload without text + /// Creates a MMS payload without text. /// - /// Receiver phone number - /// Encoding type + /// Receiver phone number. + /// Encoding type. public MMS(string number, MMSEncoding encoding = MMSEncoding.MMS) { this.number = number; @@ -22,11 +25,11 @@ public MMS(string number, MMSEncoding encoding = MMSEncoding.MMS) } /// - /// Creates a MMS payload with text (subject) + /// Creates a MMS payload with text (subject). /// - /// Receiver phone number - /// Text of the MMS - /// Encoding type + /// Receiver phone number. + /// Text of the MMS. + /// Encoding type. public MMS(string number, string subject, MMSEncoding encoding = MMSEncoding.MMS) { this.number = number; @@ -34,11 +37,15 @@ public MMS(string number, string subject, MMSEncoding encoding = MMSEncoding.MMS this.encoding = encoding; } + /// + /// Returns the MMS payload as a string. + /// + /// The MMS payload as a string. public override string ToString() { - var returnVal = string.Empty; + var returnVal = string.Empty; switch (this.encoding) - { + { case MMSEncoding.MMSTO: var queryStringMmsTo = string.Empty; if (!string.IsNullOrEmpty(this.subject)) @@ -55,9 +62,19 @@ public override string ToString() return returnVal; } + /// + /// Defines the encoding types for the MMS payload. + /// public enum MMSEncoding { + /// + /// Uses the "mms:" URI scheme. + /// MMS, + + /// + /// Uses the "mmsto:" URI scheme. + /// MMSTO } } diff --git a/QRCoder/PayloadGenerator/Mail.cs b/QRCoder/PayloadGenerator/Mail.cs index 6ef23d3d..fd08b91b 100644 --- a/QRCoder/PayloadGenerator/Mail.cs +++ b/QRCoder/PayloadGenerator/Mail.cs @@ -6,18 +6,21 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates an email payload that can be used to create a QR code for sending an email. + /// public class Mail : Payload { private readonly string? mailReceiver, subject, message; private readonly MailEncoding encoding; - + /// - /// Creates an email payload with subject and message/text + /// Creates an email payload with subject and message/text. /// - /// Receiver's email address - /// Subject line of the email - /// Message content of the email + /// Receiver's email address. + /// Subject line of the email. + /// Message content of the email. /// Payload encoding type. Choose dependent on your QR Code scanner app. public Mail(string? mailReceiver = null, string? subject = null, string? message = null, MailEncoding encoding = MailEncoding.MAILTO) { @@ -27,6 +30,10 @@ public Mail(string? mailReceiver = null, string? subject = null, string? message this.encoding = encoding; } + /// + /// Returns the email payload as a string. + /// + /// The email payload as a string. public override string ToString() { var returnVal = string.Empty; @@ -51,10 +58,24 @@ public override string ToString() return returnVal; } + /// + /// Defines the encoding types for the email payload. + /// public enum MailEncoding { + /// + /// Uses the "mailto:" URI scheme. + /// MAILTO, + + /// + /// Uses the "MATMSG:" format. + /// MATMSG, + + /// + /// Uses the "SMTP:" format. + /// SMTP } } diff --git a/QRCoder/PayloadGenerator/MoneroTransaction.cs b/QRCoder/PayloadGenerator/MoneroTransaction.cs index acedf10f..e40b84d8 100644 --- a/QRCoder/PayloadGenerator/MoneroTransaction.cs +++ b/QRCoder/PayloadGenerator/MoneroTransaction.cs @@ -4,6 +4,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a Monero transaction payload for QR codes. + /// public class MoneroTransaction : Payload { private readonly string address; @@ -11,13 +14,14 @@ public class MoneroTransaction : Payload private readonly float? txAmount; /// - /// Creates a monero transaction payload + /// Creates a Monero transaction payload. /// - /// Receiver's monero address - /// Amount to transfer - /// Payment id - /// Receipient's name - /// Reference text / payment description + /// Receiver's Monero address. + /// Amount to transfer. + /// Payment ID. + /// Recipient's name. + /// Reference text / payment description. + /// Thrown when the address is null or empty, or when the txAmount is less than or equal to 0. public MoneroTransaction(string address, float? txAmount = null, string? txPaymentId = null, string? recipientName = null, string? txDescription = null) { if (string.IsNullOrEmpty(address)) @@ -31,6 +35,10 @@ public MoneroTransaction(string address, float? txAmount = null, string? txPayme this.txDescription = txDescription; } + /// + /// Returns the Monero transaction payload as a URI string. + /// + /// The Monero transaction payload as a URI string. public override string ToString() { var moneroUri = $"monero://{address}{(!string.IsNullOrEmpty(txPaymentId) || !string.IsNullOrEmpty(recipientName) || !string.IsNullOrEmpty(txDescription) || txAmount != null ? "?" : string.Empty)}"; @@ -42,17 +50,32 @@ public override string ToString() } + /// + /// Exception class for Monero transaction errors. + /// public class MoneroTransactionException : Exception { + /// + /// Initializes a new instance of the class. + /// public MoneroTransactionException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public MoneroTransactionException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The message that describes the error. + /// The exception that is the cause of the current exception. public MoneroTransactionException(string message, Exception inner) : base(message, inner) { diff --git a/QRCoder/PayloadGenerator/OneTimePassword.cs b/QRCoder/PayloadGenerator/OneTimePassword.cs index 672919dc..3d55dca6 100644 --- a/QRCoder/PayloadGenerator/OneTimePassword.cs +++ b/QRCoder/PayloadGenerator/OneTimePassword.cs @@ -5,14 +5,31 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a payload for One Time Password (OTP) used in applications like Google Authenticator. + /// public class OneTimePassword : Payload { //https://github.com/google/google-authenticator/wiki/Key-Uri-Format + + /// + /// The type of OTP (TOTP or HOTP). + /// public OneTimePasswordAuthType Type { get; set; } = OneTimePasswordAuthType.TOTP; + + /// + /// The secret key used for OTP generation. + /// public string Secret { get; set; } = null!; + /// + /// The hashing algorithm used for OTP (SHA1, SHA256, SHA512). + /// public OneTimePasswordAuthAlgorithm AuthAlgorithm { get; set; } = OneTimePasswordAuthAlgorithm.SHA1; + /// + /// Obsolete. Use instead. + /// [Obsolete("This property is obsolete, use " + nameof(AuthAlgorithm) + " instead", false)] public OoneTimePasswordAuthAlgorithm Algorithm { @@ -20,18 +37,43 @@ public OoneTimePasswordAuthAlgorithm Algorithm set { AuthAlgorithm = (OneTimePasswordAuthAlgorithm)Enum.Parse(typeof(OneTimePasswordAuthAlgorithm), value.ToString()); } } + /// + /// The issuer of the OTP (usually the service or company name). + /// public string? Issuer { get; set; } + + /// + /// The label for the OTP (usually the user's email or username). + /// public string? Label { get; set; } + + /// + /// The number of digits in the OTP (default is 6). + /// public int Digits { get; set; } = 6; + + /// + /// The counter value for HOTP (only used if Type is HOTP). + /// public int? Counter { get; set; } = null; + + /// + /// The period in seconds for TOTP (default is 30). + /// public int? Period { get; set; } = 30; + /// + /// Enum for OTP types. + /// public enum OneTimePasswordAuthType { TOTP, HOTP, } + /// + /// Enum for hashing algorithms used in OTP. + /// public enum OneTimePasswordAuthAlgorithm { SHA1, @@ -39,6 +81,9 @@ public enum OneTimePasswordAuthAlgorithm SHA512, } + /// + /// Obsolete. Use instead. + /// [Obsolete("This enum is obsolete, use " + nameof(OneTimePasswordAuthAlgorithm) + " instead", false)] public enum OoneTimePasswordAuthAlgorithm { @@ -47,6 +92,10 @@ public enum OoneTimePasswordAuthAlgorithm SHA512, } + /// + /// Returns the OTP payload as a string. + /// + /// The OTP payload as a string. public override string ToString() { switch (Type) @@ -62,6 +111,11 @@ public override string ToString() // Note: Issuer:Label must only contain 1 : if either of the Issuer or the Label has a : then it is invalid. // Defaults are 6 digits and 30 for Period + + /// + /// Returns the HOTP payload as a string. + /// + /// The HOTP payload as a string. private string HMACToString() { var sb = new StringBuilder("otpauth://hotp/"); @@ -71,6 +125,10 @@ private string HMACToString() return sb.ToString(); } + /// + /// Returns the TOTP payload as a string. + /// + /// The TOTP payload as a string. private string TimeToString() { if (Period == null) @@ -90,6 +148,10 @@ private string TimeToString() return sb.ToString(); } + /// + /// Processes the common fields for both TOTP and HOTP. + /// + /// StringBuilder to append the common fields. private void ProcessCommonFields(StringBuilder sb) { if (Secret.IsNullOrWhiteSpace()) diff --git a/QRCoder/PayloadGenerator/Payload.cs b/QRCoder/PayloadGenerator/Payload.cs index af6ee9d9..180df7ad 100644 --- a/QRCoder/PayloadGenerator/Payload.cs +++ b/QRCoder/PayloadGenerator/Payload.cs @@ -1,12 +1,34 @@ namespace QRCoder { + /// + /// Contains classes and methods for generating payloads for QR codes. + /// public static partial class PayloadGenerator { + /// + /// Represents the base class for all QR code payloads. + /// public abstract class Payload { + /// + /// Gets the version of the QR code payload. + /// public virtual int Version { get { return -1; } } + + /// + /// Gets the error correction level of the QR code payload. + /// public virtual QRCodeGenerator.ECCLevel EccLevel { get { return QRCodeGenerator.ECCLevel.Default; } } + + /// + /// Gets the ECI mode of the QR code payload. + /// public virtual QRCodeGenerator.EciMode EciMode { get { return QRCodeGenerator.EciMode.Default; } } + + /// + /// Returns a string representation of the QR code payload. + /// + /// A string representation of the QR code payload. public abstract override string ToString(); } } diff --git a/QRCoder/PayloadGenerator/PhoneNumber.cs b/QRCoder/PayloadGenerator/PhoneNumber.cs index 7d30cac9..2092fc07 100644 --- a/QRCoder/PayloadGenerator/PhoneNumber.cs +++ b/QRCoder/PayloadGenerator/PhoneNumber.cs @@ -2,19 +2,26 @@ { public static partial class PayloadGenerator { + /// + /// Generates a phone call payload. + /// public class PhoneNumber : Payload { private readonly string number; /// - /// Generates a phone call payload + /// Initializes a new instance of the class. /// - /// Phonenumber of the receiver + /// Phone number of the receiver. public PhoneNumber(string number) { this.number = number; } + /// + /// Returns the phone call payload as a string. + /// + /// The phone call payload as a string. public override string ToString() { return $"tel:{this.number}"; diff --git a/QRCoder/PayloadGenerator/RussiaPaymentOrder.cs b/QRCoder/PayloadGenerator/RussiaPaymentOrder.cs index 9bf96753..3121c671 100644 --- a/QRCoder/PayloadGenerator/RussiaPaymentOrder.cs +++ b/QRCoder/PayloadGenerator/RussiaPaymentOrder.cs @@ -11,6 +11,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a payload for a Russian payment order. + /// public class RussiaPaymentOrder : Payload { // Specification of RussianPaymentOrder @@ -35,8 +38,8 @@ private RussiaPaymentOrder() } /// - /// Generates a RussiaPaymentOrder payload - /// + /// Initializes a new instance of the class. + /// /// Name of the payee (Наименование получателя платежа) /// Beneficiary account number (Номер счета получателя платежа) /// Name of the beneficiary's bank (Наименование банка получателя платежа) @@ -58,10 +61,10 @@ public RussiaPaymentOrder(string name, string personalAcc, string bankName, stri } /// - /// Returns payload as string. + /// Returns the payload as a string. /// /// ⚠ Attention: If CharacterSets was set to windows-1251 or koi8-r you should use ToBytes() instead of ToString() and pass the bytes to CreateQrCode()! - /// + /// The payload as a string. public override string ToString() { var cp = characterSet.ToString().Replace("_", "-"); @@ -74,10 +77,10 @@ public override string ToString() } /// - /// Returns payload as byte[]. + /// Returns the payload as a byte array. /// - /// Should be used if CharacterSets equals windows-1251 or koi8-r - /// + /// Should be used if CharacterSets equals windows-1251 or koi8-r. + /// The payload as a byte array. public byte[] ToBytes() { @@ -233,6 +236,9 @@ private class MandatoryFields public string CorrespAcc = null!; } + /// + /// Represents optional fields for the RussiaPaymentOrder. + /// public class OptionalFields { private string? _sum; @@ -595,16 +601,36 @@ public enum TechCode Прочие_услуги = 15 } + /// + /// Specifies character sets for encoding the RussiaPaymentOrder payload. + /// public enum CharacterSets { - windows_1251 = 1, // Encoding.GetEncoding("windows-1251") - utf_8 = 2, // Encoding.UTF8 - koi8_r = 3 // Encoding.GetEncoding("koi8-r") + /// + /// Windows-1251 encoding. + /// + windows_1251 = 1, + /// + /// UTF-8 encoding. + /// + utf_8 = 2, + + /// + /// KOI8-R encoding. + /// + koi8_r = 3 } + /// + /// Represents errors that occur during the generation of a RussiaPaymentOrder payload. + /// public class RussiaPaymentOrderException : Exception { + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public RussiaPaymentOrderException(string message) : base(message) { diff --git a/QRCoder/PayloadGenerator/SMS.cs b/QRCoder/PayloadGenerator/SMS.cs index c0cee669..b09256ef 100644 --- a/QRCoder/PayloadGenerator/SMS.cs +++ b/QRCoder/PayloadGenerator/SMS.cs @@ -4,16 +4,19 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates an SMS payload. + /// public class SMS : Payload { private readonly string number, subject; private readonly SMSEncoding encoding; /// - /// Creates a SMS payload without text + /// Creates an SMS payload without text. /// - /// Receiver phone number - /// Encoding type + /// Receiver phone number. + /// Encoding type. public SMS(string number, SMSEncoding encoding = SMSEncoding.SMS) { this.number = number; @@ -22,11 +25,11 @@ public SMS(string number, SMSEncoding encoding = SMSEncoding.SMS) } /// - /// Creates a SMS payload with text (subject) + /// Creates an SMS payload with text (subject). /// - /// Receiver phone number - /// Text of the SMS - /// Encoding type + /// Receiver phone number. + /// Text of the SMS. + /// Encoding type. public SMS(string number, string subject, SMSEncoding encoding = SMSEncoding.SMS) { this.number = number; @@ -34,15 +37,19 @@ public SMS(string number, string subject, SMSEncoding encoding = SMSEncoding.SMS this.encoding = encoding; } + /// + /// Returns the SMS payload as a string. + /// + /// The SMS payload as a string. public override string ToString() { var returnVal = string.Empty; switch (this.encoding) - { + { case SMSEncoding.SMS: var queryString = string.Empty; if (!string.IsNullOrEmpty(this.subject)) - queryString = $"?body={Uri.EscapeDataString(this.subject)}"; + queryString = $"?body={Uri.EscapeDataString(this.subject)}"; returnVal = $"sms:{this.number}{queryString}"; break; case SMSEncoding.SMS_iOS: @@ -53,15 +60,27 @@ public override string ToString() break; case SMSEncoding.SMSTO: returnVal = $"SMSTO:{this.number}:{this.subject}"; - break; + break; } return returnVal; } + /// + /// Specifies the encoding type for the SMS payload. + /// public enum SMSEncoding { + /// + /// Standard SMS encoding. + /// SMS, + /// + /// SMSTO encoding. + /// SMSTO, + /// + /// SMS encoding for iOS. + /// SMS_iOS } } diff --git a/QRCoder/PayloadGenerator/ShadowSocksConfig.cs b/QRCoder/PayloadGenerator/ShadowSocksConfig.cs index a5a4278d..91ed5350 100644 --- a/QRCoder/PayloadGenerator/ShadowSocksConfig.cs +++ b/QRCoder/PayloadGenerator/ShadowSocksConfig.cs @@ -7,6 +7,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a ShadowSocks proxy config payload. + /// public class ShadowSocksConfig : Payload { private readonly string hostname, password, methodStr; @@ -71,6 +74,16 @@ public ShadowSocksConfig(string hostname, int port, string password, Method meth this(hostname, port, password, method, null, tag) { } + /// + /// Generates a ShadowSocks proxy config payload with plugin options. + /// + /// Hostname of the ShadowSocks proxy + /// Port of the ShadowSocks proxy + /// Password of the SS proxy + /// Encryption type + /// Plugin name + /// Plugin option + /// Optional tag line public ShadowSocksConfig(string hostname, int port, string password, Method method, string plugin, string? pluginOption, string? tag = null) : this(hostname, port, password, method, new Dictionary { @@ -125,6 +138,15 @@ private string UrlEncode(string i) return j; } + /// + /// Generates a ShadowSocks proxy config payload with additional parameters. + /// + /// Hostname of the ShadowSocks proxy + /// Port of the ShadowSocks proxy + /// Password of the SS proxy + /// Encryption type + /// Additional parameters + /// Optional tag line public ShadowSocksConfig(string hostname, int port, string password, Method method, Dictionary? parameters, string? tag = null) { this.hostname = Uri.CheckHostName(hostname) == UriHostNameType.IPv6 @@ -146,6 +168,10 @@ public ShadowSocksConfig(string hostname, int port, string password, Method meth ).ToArray()); } + /// + /// Converts the ShadowSocks config payload to a string. + /// + /// A string representation of the ShadowSocks config payload. public override string ToString() { if (string.IsNullOrEmpty(parameter)) @@ -162,6 +188,9 @@ public override string ToString() return $"ss://{authStringEncoded}@{hostname}:{port}/?{parameter}{(!string.IsNullOrEmpty(tag) ? $"#{tag}" : string.Empty)}"; } + /// + /// Specifies the encryption methods used by ShadowSocks. + /// public enum Method { // AEAD @@ -199,7 +228,7 @@ public enum Method BfCfb, Rc4Md5, Salsa20, - // Not standard and not in acitve use + // Not standard and not in active use DesCfb, IdeaCfb, Rc2Cfb, @@ -210,17 +239,32 @@ public enum Method Table } + /// + /// Represents errors that occur during the generation of a ShadowSocksConfig payload. + /// public class ShadowSocksConfigException : Exception { + /// + /// Initializes a new instance of the class. + /// public ShadowSocksConfigException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public ShadowSocksConfigException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The message that describes the error. + /// The exception that is the cause of the current exception. public ShadowSocksConfigException(string message, Exception inner) : base(message, inner) { diff --git a/QRCoder/PayloadGenerator/SkypeCall.cs b/QRCoder/PayloadGenerator/SkypeCall.cs index c57d04ab..554e2d2c 100644 --- a/QRCoder/PayloadGenerator/SkypeCall.cs +++ b/QRCoder/PayloadGenerator/SkypeCall.cs @@ -2,12 +2,15 @@ { public static partial class PayloadGenerator { + /// + /// Generates a Skype call payload + /// public class SkypeCall : Payload { private readonly string skypeUsername; /// - /// Generates a Skype call payload + /// Initializes a new instance of the class. /// /// Skype username which will be called public SkypeCall(string skypeUsername) @@ -15,6 +18,10 @@ public SkypeCall(string skypeUsername) this.skypeUsername = skypeUsername; } + /// + /// Converts the Skype call payload to a string. + /// + /// A string representation of the Skype call payload. public override string ToString() { return $"skype:{this.skypeUsername}?call"; diff --git a/QRCoder/PayloadGenerator/SlovenianUpnQr.cs b/QRCoder/PayloadGenerator/SlovenianUpnQr.cs index cacf6a0c..d9831180 100644 --- a/QRCoder/PayloadGenerator/SlovenianUpnQr.cs +++ b/QRCoder/PayloadGenerator/SlovenianUpnQr.cs @@ -5,6 +5,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a Slovenian UPN QR payment payload. + /// public class SlovenianUpnQr : Payload { //Keep in mind, that the ECC level has to be set to "M", version to 15 and ECI to EciMode.Iso8859_2 when generating a SlovenianUpnQr! @@ -24,19 +27,67 @@ public class SlovenianUpnQr : Payload private string _recipientSiModel = ""; private string _recipientSiReference = ""; + /// + /// Gets the version of the QR code, which is 15 for Slovenian UPN QR. + /// public override int Version { get { return 15; } } + + /// + /// Gets the error correction level of the QR code, which is M for Slovenian UPN QR. + /// public override QRCodeGenerator.ECCLevel EccLevel { get { return QRCodeGenerator.ECCLevel.M; } } + + /// + /// Gets the ECI mode of the QR code, which is Iso8859_2 for Slovenian UPN QR. + /// public override QRCodeGenerator.EciMode EciMode { get { return QRCodeGenerator.EciMode.Iso8859_2; } } + /// + /// Limits the length of a string to a specified maximum length. + /// + /// The string to limit. + /// The maximum length of the string. + /// The limited string. private string LimitLength(string value, int maxLength) { return (value.Length <= maxLength) ? value : value.Substring(0, maxLength); } + /// + /// Initializes a new instance of the class. + /// + /// The name of the payer. + /// The address of the payer. + /// The place of the payer. + /// The name of the recipient. + /// The address of the recipient. + /// The place of the recipient. + /// The IBAN of the recipient. + /// The description of the payment. + /// The amount of the payment. + /// The SI model of the recipient. + /// The SI reference of the recipient. + /// The code of the payment. public SlovenianUpnQr(string payerName, string payerAddress, string payerPlace, string recipientName, string recipientAddress, string recipientPlace, string recipientIban, string description, double amount, string recipientSiModel = "SI00", string recipientSiReference = "", string code = "OTHR") : this(payerName, payerAddress, payerPlace, recipientName, recipientAddress, recipientPlace, recipientIban, description, amount, null, recipientSiModel, recipientSiReference, code) { } + /// + /// Initializes a new instance of the class with a deadline. + /// + /// The name of the payer. + /// The address of the payer. + /// The place of the payer. + /// The name of the recipient. + /// The address of the recipient. + /// The place of the recipient. + /// The IBAN of the recipient. + /// The description of the payment. + /// The amount of the payment. + /// The deadline for the payment. + /// The SI model of the recipient. + /// The SI reference of the recipient. + /// The code of the payment. public SlovenianUpnQr(string payerName, string payerAddress, string payerPlace, string recipientName, string recipientAddress, string recipientPlace, string recipientIban, string description, double amount, DateTime? deadline, string recipientSiModel = "SI99", string recipientSiReference = "", string code = "OTHR") { _payerName = LimitLength(payerName.Trim(), 33); @@ -53,14 +104,23 @@ public SlovenianUpnQr(string payerName, string payerAddress, string payerPlace, _recipientSiModel = LimitLength(recipientSiModel.Trim().ToUpper(), 4); _recipientSiReference = LimitLength(recipientSiReference.Trim(), 22); } - + + /// + /// Formats the amount as a string with leading zeros. + /// + /// The amount to format. + /// The formatted amount string. private string FormatAmount(double amount) { int _amt = (int)Math.Round(amount * 100.0); return String.Format("{0:00000000000}", _amt); } + /// + /// Calculates the checksum of the payment data. + /// + /// The checksum of the payment data. private int CalculateChecksum() { int _cs = 5 + _payerName.Length; //5 = UPNQR constant Length @@ -80,6 +140,10 @@ private int CalculateChecksum() return _cs; } + /// + /// Returns the Slovenian UPN QR payment data as a string. + /// + /// The Slovenian UPN QR payment data as a string. public override string ToString() { var _sb = new StringBuilder(); diff --git a/QRCoder/PayloadGenerator/SwissQrCode.cs b/QRCoder/PayloadGenerator/SwissQrCode.cs index 225563d5..f2f898de 100644 --- a/QRCoder/PayloadGenerator/SwissQrCode.cs +++ b/QRCoder/PayloadGenerator/SwissQrCode.cs @@ -7,6 +7,9 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates the payload for a SwissQrCode. + /// public class SwissQrCode : Payload { //Keep in mind, that the ECC level has to be set to "M" when generating a SwissQrCode! @@ -26,7 +29,9 @@ public class SwissQrCode : Payload private readonly Reference reference; private readonly AdditionalInformation additionalInformation; + /// public override QRCodeGenerator.ECCLevel EccLevel { get { return QRCodeGenerator.ECCLevel.M; } } + /// public override QRCodeGenerator.EciMode EciMode { get { return QRCodeGenerator.EciMode.Utf8; } } /// @@ -73,6 +78,9 @@ public SwissQrCode(Iban iban, Currency currency, Contact creditor, Reference ref this.alternativeProcedure2 = alternativeProcedure2; } + /// + /// Represents additional information for the SwissQrCode. + /// public class AdditionalInformation { private readonly string trailer; @@ -92,33 +100,57 @@ public AdditionalInformation(string? unstructuredMessage = null, string? billInf this.trailer = "EPD"; } + /// + /// Gets the unstructured message. + /// public string? UnstructureMessage { get { return !string.IsNullOrEmpty(unstructuredMessage) ? unstructuredMessage!.Replace("\n", "") : null; } } - + + /// + /// Gets the bill information. + /// public string? BillInformation { get { return !string.IsNullOrEmpty(billInformation) ? billInformation!.Replace("\n", "") : null; } } - + + /// + /// Gets the trailer. + /// public string Trailer { get { return trailer; } } + /// + /// Represents exceptions specific to SwissQrCode additional information. + /// public class SwissQrCodeAdditionalInformationException : Exception { + /// + /// Initializes a new instance of the class. + /// public SwissQrCodeAdditionalInformationException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public SwissQrCodeAdditionalInformationException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception. public SwissQrCodeAdditionalInformationException(string message, Exception inner) : base(message, inner) { @@ -126,6 +158,9 @@ public SwissQrCodeAdditionalInformationException(string message, Exception inner } } + /// + /// Represents reference information for the SwissQrCode. + /// public class Reference { private readonly ReferenceType referenceType; @@ -159,42 +194,81 @@ public Reference(ReferenceType referenceType, string? reference = null, Referenc this.reference = reference; } + /// + /// Gets the reference type. + /// public ReferenceType RefType { get { return referenceType; } } + /// + /// Gets the reference text. + /// public string? ReferenceText { get { return !string.IsNullOrEmpty(reference) ? reference!.Replace("\n", "") : null; } } - + /// - /// Reference type. When using a QR-IBAN you have to use either "QRR" or "SCOR" + /// Reference type. When using a QR-IBAN you have to use either "QRR" or "SCOR". /// public enum ReferenceType { + /// + /// QR Reference + /// QRR, + /// + /// Creditor Reference + /// SCOR, + /// + /// No Reference + /// NON } + /// + /// Represents the text type for the reference. + /// public enum ReferenceTextType { + /// + /// QR Reference Text + /// QrReference, + /// + /// Creditor Reference ISO 11649 + /// CreditorReferenceIso11649 } + /// + /// Represents exceptions specific to SwissQrCode references. + /// public class SwissQrCodeReferenceException : Exception { + /// + /// Initializes a new instance of the class. + /// public SwissQrCodeReferenceException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public SwissQrCodeReferenceException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception. public SwissQrCodeReferenceException(string message, Exception inner) : base(message, inner) { @@ -202,6 +276,9 @@ public SwissQrCodeReferenceException(string message, Exception inner) } } + /// + /// Represents an IBAN with type information. + /// public class Iban { private string iban; @@ -224,33 +301,64 @@ public Iban(string iban, IbanType ibanType) this.ibanType = ibanType; } + /// + /// Gets a value indicating whether this is a QR-IBAN. + /// public bool IsQrIban { get { return ibanType == IbanType.QrIban; } } + /// + /// Converts the IBAN object to its string representation. + /// + /// A string representation of the IBAN. public override string ToString() { return iban.Replace("-", "").Replace("\n", "").Replace(" ",""); } + /// + /// Represents the type of IBAN. + /// public enum IbanType { + /// + /// Regular IBAN + /// Iban, + /// + /// QR-IBAN + /// QrIban } + /// + /// Represents exceptions specific to SwissQrCode IBANs. + /// public class SwissQrCodeIbanException : Exception { + /// + /// Initializes a new instance of the class. + /// public SwissQrCodeIbanException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public SwissQrCodeIbanException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception. public SwissQrCodeIbanException(string message, Exception inner) : base(message, inner) { @@ -258,6 +366,9 @@ public SwissQrCodeIbanException(string message, Exception inner) } } + /// + /// Represents contact information. + /// public class Contact { private static readonly HashSet twoLetterCodes = ValidTwoLetterCodes(); @@ -293,11 +404,17 @@ public Contact(string name, string country, string addressLine1, string addressL { } + /// + /// Creates a contact with structured address. + /// public static Contact WithStructuredAddress(string name, string zipCode, string city, string country, string? street = null, string? houseNumber = null) { return new Contact(name, zipCode, city, country, street, houseNumber, AddressType.StructuredAddress); } + /// + /// Creates a contact with combined address. + /// public static Contact WithCombinedAddress(string name, string country, string addressLine1, string addressLine2) { return new Contact(name, null, null, country, addressLine1, addressLine2, AddressType.CombinedAddress); @@ -384,6 +501,10 @@ private static HashSet ValidTwoLetterCodes() return new HashSet(codes, StringComparer.OrdinalIgnoreCase); } + /// + /// Returns a string that represents the contact information in the format required for Swiss QR codes. + /// + /// A string representing the contact information. public override string ToString() { string contactData = $"{(AddressType.StructuredAddress == adrType ? "S" : "K")}{br}"; //AdrTp @@ -396,23 +517,47 @@ public override string ToString() return contactData; } + /// + /// Defines the type of address. + /// public enum AddressType { + /// + /// Structured Address + /// StructuredAddress, + /// + /// Combined Address + /// CombinedAddress } + /// + /// Represents errors that occur during the creation of a Swiss QR code contact. + /// public class SwissQrCodeContactException : Exception { + /// + /// Initializes a new instance of the class. + /// public SwissQrCodeContactException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public SwissQrCodeContactException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception, or a null reference if no inner exception is specified. public SwissQrCodeContactException(string message, Exception inner) : base(message, inner) { @@ -420,6 +565,10 @@ public SwissQrCodeContactException(string message, Exception inner) } } + /// + /// Returns a string that represents the entire Swiss QR code payload. + /// + /// A string representing the Swiss QR code payload. public override string ToString() { //Header "logical" element @@ -480,25 +629,46 @@ public override string ToString() /// - /// ISO 4217 currency codes + /// ISO 4217 currency codes. /// public enum Currency { + /// + /// Swiss Franc + /// CHF = 756, + /// + /// Euro + /// EUR = 978 } + /// + /// Represents errors that occur during Swiss QR Code generation. + /// public class SwissQrCodeException : Exception { + /// + /// Initializes a new instance of the class. + /// public SwissQrCodeException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// + /// The message that describes the error. public SwissQrCodeException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception, or a null reference if no inner exception is specified. public SwissQrCodeException(string message, Exception inner) : base(message, inner) { diff --git a/QRCoder/PayloadGenerator/Url.cs b/QRCoder/PayloadGenerator/Url.cs index 8b6f09d0..e3580c8c 100644 --- a/QRCoder/PayloadGenerator/Url.cs +++ b/QRCoder/PayloadGenerator/Url.cs @@ -4,19 +4,26 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a URL payload for QR codes. + /// public class Url : Payload { private readonly string url; /// - /// Generates a link. If the protocol is not specified, the http protocol will be added. + /// Initializes a new instance of the class. /// - /// Link url target + /// The target URL. If the protocol is not specified, the http protocol will be added. public Url(string url) { this.url = url; } + /// + /// Returns the URL payload as a string. + /// + /// The URL payload as a string, ensuring it starts with "http://" if no protocol is specified. public override string ToString() { return (!this.url.StartsWith("http", StringComparison.OrdinalIgnoreCase) ? "http://" + this.url : this.url); diff --git a/QRCoder/PayloadGenerator/WhatsAppMessage.cs b/QRCoder/PayloadGenerator/WhatsAppMessage.cs index 59379a90..9091b00a 100644 --- a/QRCoder/PayloadGenerator/WhatsAppMessage.cs +++ b/QRCoder/PayloadGenerator/WhatsAppMessage.cs @@ -5,18 +5,21 @@ namespace QRCoder { public static partial class PayloadGenerator { + /// + /// Generates a WhatsApp message payload for QR codes. + /// public class WhatsAppMessage : Payload { private readonly string number, message; /// - /// Let's you compose a WhatApp message and send it the receiver number. + /// Initializes a new instance of the class with a receiver number and message. /// - /// Receiver phone number where the is a full phone number in international format. - /// Omit any zeroes, brackets, or dashes when adding the phone number in international format. - /// Use: 1XXXXXXXXXX | Don't use: +001-(XXX)XXXXXXX + /// + /// Receiver phone number in full international format. + /// Omit any zeroes, brackets, or dashes. Use format: 1XXXXXXXXXX. Don't use: +001-(XXX)XXXXXXX. /// - /// The message + /// The message to be sent. public WhatsAppMessage(string number, string message) { this.number = number; @@ -24,15 +27,20 @@ public WhatsAppMessage(string number, string message) } /// - /// Let's you compose a WhatApp message. When scanned the user is asked to choose a contact who will receive the message. + /// Initializes a new instance of the class with a message only. + /// When scanned, the user is asked to choose a contact to receive the message. /// - /// The message + /// The message to be sent. public WhatsAppMessage(string message) { this.number = string.Empty; this.message = message; } + /// + /// Returns the WhatsApp message payload as a string. + /// + /// The WhatsApp message URL as a string. public override string ToString() { var cleanedPhone = Regex.Replace(this.number, @"^[0+]+|[ ()-]", string.Empty); diff --git a/QRCoder/PayloadGenerator/WiFi.cs b/QRCoder/PayloadGenerator/WiFi.cs index 70efe2a7..9e699977 100644 --- a/QRCoder/PayloadGenerator/WiFi.cs +++ b/QRCoder/PayloadGenerator/WiFi.cs @@ -2,19 +2,22 @@ { public static partial class PayloadGenerator { + /// + /// Generates a WiFi payload. Scanned by a QR Code scanner app, the device will connect to the WiFi. + /// public class WiFi : Payload { private readonly string ssid, password, authenticationMode; private readonly bool isHiddenSsid; /// - /// Generates a WiFi payload. Scanned by a QR Code scanner app, the device will connect to the WiFi. + /// Initializes a new instance of the class. /// /// SSID of the WiFi network /// Password of the WiFi network - /// Authentification mode (WEP, WPA, WPA2) - /// Set flag, if the WiFi network hides its SSID - /// Set flag, if ssid/password is delivered as HEX string. Note: May not be supported on iOS devices. + /// Authentication mode (WEP, WPA, WPA2) + /// Set flag if the WiFi network hides its SSID + /// Set flag if ssid/password is delivered as HEX string. Note: May not be supported on iOS devices. public WiFi(string ssid, string password, Authentication authenticationMode, bool isHiddenSSID = false, bool escapeHexStrings = true) { this.ssid = EscapeInput(ssid); @@ -25,17 +28,35 @@ public WiFi(string ssid, string password, Authentication authenticationMode, boo this.isHiddenSsid = isHiddenSSID; } + /// + /// Returns the WiFi payload as a string. + /// public override string ToString() { return $"WIFI:T:{this.authenticationMode};S:{this.ssid};P:{this.password};{(this.isHiddenSsid ? "H:true" : string.Empty)};"; } + /// + /// Specifies the authentication mode for the WiFi network. + /// public enum Authentication { + /// + /// WEP authentication mode + /// WEP, + /// + /// WPA authentication mode + /// WPA, + /// + /// No password authentication mode + /// nopass, + /// + /// WPA2 authentication mode + /// WPA2 } } diff --git a/QRCoder/PdfByteQRCode.cs b/QRCoder/PdfByteQRCode.cs index 14854139..8b039901 100644 --- a/QRCoder/PdfByteQRCode.cs +++ b/QRCoder/PdfByteQRCode.cs @@ -11,6 +11,9 @@ namespace QRCoder { + /// + /// Represents a QR code generator that outputs QR codes as PDF byte arrays. + /// #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif @@ -20,27 +23,32 @@ public class PdfByteQRCode : AbstractQRCode, IDisposable private readonly byte[] pdfBinaryComment = new byte[] { 0x25, 0xe2, 0xe3, 0xcf, 0xd3 }; /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public PdfByteQRCode() { } + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public PdfByteQRCode(QRCodeData data) : base(data) { } /// - /// Creates a PDF document with a black & white QR code + /// Creates a PDF document with a black and white QR code. /// - /// - /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a PDF byte array. public byte[] GetGraphic(int pixelsPerModule) { return GetGraphic(pixelsPerModule, "#000000", "#ffffff"); } /// - /// Takes hexadecimal color string #000000 and returns byte[]{ 0, 0, 0 } + /// Converts a hexadecimal color string to a byte array. /// - /// Color in HEX format like #ffffff - /// + /// Color in HEX format like #ffffff. + /// Returns the color as a byte array. private byte[] HexColorToByteArray(string colorString) { if (colorString.StartsWith("#")) @@ -52,14 +60,14 @@ private byte[] HexColorToByteArray(string colorString) } /// - /// Creates a PDF document with given colors DPI and quality + /// Creates a PDF document with specified colors, DPI, and quality. /// - /// - /// - /// - /// - /// - /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// The DPI (dots per inch) of the PDF document. + /// The JPEG quality of the PDF document. + /// Returns the QR code graphic as a PDF byte array. public byte[] GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, int dpi = 150, long jpgQuality = 85) { byte[] jpgArray, pngArray; @@ -70,7 +78,7 @@ public byte[] GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string li using (var qrCode = new PngByteQRCode(QrCodeData)) { pngArray = qrCode.GetGraphic(pixelsPerModule, HexColorToByteArray(darkColorHtmlHex), HexColorToByteArray(lightColorHtmlHex)); - } + } //Create image and transofrm to JPG using (var msPng = new MemoryStream()) @@ -88,7 +96,7 @@ public byte[] GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string li jpgArray = msJpeg.ToArray(); } } - + //Create PDF document using (var stream = new MemoryStream()) { @@ -216,8 +224,24 @@ public byte[] GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string li #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif + /// + /// Provides static methods for creating PDF byte array QR codes. + /// public static class PdfByteQRCodeHelper { + /// + /// Creates a PDF byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Returns the QR code graphic as a PDF byte array. public static byte[] GetQRCode(string plainText, int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1) @@ -230,6 +254,13 @@ public static byte[] GetQRCode(string plainText, int pixelsPerModule, string dar return qrCode.GetGraphic(pixelsPerModule, darkColorHtmlHex, lightColorHtmlHex); } + /// + /// Creates a PDF byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The level of error correction data. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a PDF byte array. public static byte[] GetQRCode(string txt, ECCLevel eccLevel, int size) { using (var qrGen = new QRCodeGenerator()) @@ -240,4 +271,4 @@ public static byte[] GetQRCode(string txt, ECCLevel eccLevel, int size) } } } -#endif \ No newline at end of file +#endif diff --git a/QRCoder/PngByteQRCode.cs b/QRCoder/PngByteQRCode.cs index c21ada11..757b8e05 100644 --- a/QRCoder/PngByteQRCode.cs +++ b/QRCoder/PngByteQRCode.cs @@ -5,21 +5,32 @@ namespace QRCoder { + /// + /// Represents a QR code generator that outputs QR codes as PNG byte arrays. + /// public sealed class PngByteQRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public PngByteQRCode() { } + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public PngByteQRCode(QRCodeData data) : base(data) { } /// - /// Creates a black & white PNG of the QR code, using 1-bit grayscale. + /// Creates a black and white PNG of the QR code, using 1-bit grayscale. /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a PNG byte array. public byte[] GetGraphic(int pixelsPerModule, bool drawQuietZones = true) { using (var png = new PngBuilder()) @@ -33,8 +44,13 @@ public byte[] GetGraphic(int pixelsPerModule, bool drawQuietZones = true) } /// - /// Creates 2-color PNG of the QR code, using 1-bit indexed color. Accepts 3-byte RGB colors for normal images and 4-byte RGBA-colors for transparent images. + /// Creates a 2-color PNG of the QR code, using 1-bit indexed color. Accepts 3-byte RGB colors for normal images and 4-byte RGBA-colors for transparent images. /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules as an RGBA byte array. + /// The color of the light modules as an RGBA byte array. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a PNG byte array. public byte[] GetGraphic(int pixelsPerModule, byte[] darkColorRgba, byte[] lightColorRgba, bool drawQuietZones = true) { using (var png = new PngBuilder()) @@ -51,6 +67,9 @@ public byte[] GetGraphic(int pixelsPerModule, byte[] darkColorRgba, byte[] light /// /// Creates a bitmap where each pixel is represented by a single bit, dark = 0 and light = 1. /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the bitmap as a byte array. private byte[] DrawScanlines(int pixelsPerModule, bool drawQuietZones) { var moduleMatrix = this.QrCodeData.ModuleMatrix; @@ -80,7 +99,7 @@ private byte[] DrawScanlines(int pixelsPerModule, bool drawQuietZones) } } - // Copy the scanline required number of times. + // Copy the scanline the required number of times. for (var copyCount = 1; copyCount < pixelsPerModule; copyCount++) { Array.Copy(scanlines, scanlineOffset, scanlines, scanlineOffset + copyCount * bytesPerScanline, bytesPerScanline); @@ -318,8 +337,25 @@ private static uint Crc32(byte[] data, int index, int length) } } + /// + /// Provides static methods for creating PNG byte array QR codes. + /// public static class PngByteQRCodeHelper { + /// + /// Creates a PNG byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules as an RGBA byte array. + /// The color of the light modules as an RGBA byte array. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a PNG byte array. public static byte[] GetQRCode(string plainText, int pixelsPerModule, byte[] darkColorRgba, byte[] lightColorRgba, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, bool drawQuietZones = true) { using (var qrGenerator = new QRCodeGenerator()) @@ -327,9 +363,17 @@ public static byte[] GetQRCode(string plainText, int pixelsPerModule, byte[] dar using (var qrCode = new PngByteQRCode(qrCodeData)) return qrCode.GetGraphic(pixelsPerModule, darkColorRgba, lightColorRgba, drawQuietZones); } - + + /// + /// Creates a PNG byte array QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The level of error correction data. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a PNG byte array. public static byte[] GetQRCode(string txt, QRCodeGenerator.ECCLevel eccLevel, int size, bool drawQuietZones = true) { using (var qrGen = new QRCodeGenerator()) @@ -337,5 +381,5 @@ public static byte[] GetQRCode(string txt, QRCodeGenerator.ECCLevel eccLevel, in using (var qrPng = new PngByteQRCode(qrCode)) return qrPng.GetGraphic(size, drawQuietZones); } - } + } } diff --git a/QRCoder/PostscriptQRCode.cs b/QRCoder/PostscriptQRCode.cs index d0484a9b..97d09a19 100644 --- a/QRCoder/PostscriptQRCode.cs +++ b/QRCoder/PostscriptQRCode.cs @@ -1,46 +1,105 @@ -#if !NETSTANDARD1_3 + +#if !NETSTANDARD1_3 using System; using System.Drawing; using static QRCoder.QRCodeGenerator; namespace QRCoder { - + /// + /// Represents a QR code generator that outputs QR codes as PostScript code. + /// public class PostscriptQRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public PostscriptQRCode() { } + + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public PostscriptQRCode(QRCodeData data) : base(data) { } + /// + /// Creates a black and white PostScript code representation of the QR code. + /// + /// The number of points each dark/light module of the QR code will occupy in the final QR code image. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(int pointsPerModule, bool epsFormat = false) { var viewBox = new Size(pointsPerModule * this.QrCodeData.ModuleMatrix.Count, pointsPerModule * this.QrCodeData.ModuleMatrix.Count); return this.GetGraphic(viewBox, Color.Black, Color.White, true, epsFormat); } + + /// + /// Creates a colored PostScript code representation of the QR code. + /// + /// The number of points each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(int pointsPerModule, Color darkColor, Color lightColor, bool drawQuietZones = true, bool epsFormat = false) { var viewBox = new Size(pointsPerModule * this.QrCodeData.ModuleMatrix.Count, pointsPerModule * this.QrCodeData.ModuleMatrix.Count); return this.GetGraphic(viewBox, darkColor, lightColor, drawQuietZones, epsFormat); } + /// + /// Creates a colored PostScript code representation of the QR code. + /// + /// The number of points each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(int pointsPerModule, string darkColorHex, string lightColorHex, bool drawQuietZones = true, bool epsFormat = false) { var viewBox = new Size(pointsPerModule * this.QrCodeData.ModuleMatrix.Count, pointsPerModule * this.QrCodeData.ModuleMatrix.Count); return this.GetGraphic(viewBox, darkColorHex, lightColorHex, drawQuietZones, epsFormat); } + /// + /// Creates a black and white PostScript code representation of the QR code. + /// + /// The dimensions of the viewbox for the QR code. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(Size viewBox, bool drawQuietZones = true, bool epsFormat = false) { return this.GetGraphic(viewBox, Color.Black, Color.White, drawQuietZones, epsFormat); } + /// + /// Creates a colored PostScript code representation of the QR code. + /// + /// The dimensions of the viewbox for the QR code. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(Size viewBox, string darkColorHex, string lightColorHex, bool drawQuietZones = true, bool epsFormat = false) { return this.GetGraphic(viewBox, ColorTranslator.FromHtml(darkColorHex), ColorTranslator.FromHtml(lightColorHex), drawQuietZones, epsFormat); } + /// + /// Creates a colored PostScript code representation of the QR code. + /// + /// The dimensions of the viewbox for the QR code. + /// The color of the dark modules. + /// The color of the light modules. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public string GetGraphic(Size viewBox, Color darkColor, Color lightColor, bool drawQuietZones = true, bool epsFormat = false) { var offset = drawQuietZones ? 0 : 4; @@ -70,9 +129,13 @@ public string GetGraphic(Size viewBox, Color darkColor, Color lightColor, bool d return psFile + psFooter; } + /// + /// Cleans double values for international use/formats. + /// + /// The input double value. + /// Returns the cleaned string representation of the double value. private string CleanSvgVal(double input) { - //Clean double values for international use/formats return input.ToString(System.Globalization.CultureInfo.InvariantCulture); } @@ -140,8 +203,26 @@ sc sc scale "; } + /// + /// Provides static methods for creating PostScript QR codes. + /// public static class PostscriptQRCodeHelper { + /// + /// Creates a PostScript QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of points each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Indicates if quiet zones around the QR code should be drawn. + /// Indicates if the output should be in EPS format. + /// Returns the QR code graphic as a PostScript string. public static string GetQRCode(string plainText, int pointsPerModule, string darkColorHex, string lightColorHex, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, bool drawQuietZones = true, bool epsFormat = false) { using (var qrGenerator = new QRCodeGenerator()) @@ -151,4 +232,4 @@ public static string GetQRCode(string plainText, int pointsPerModule, string dar } } } -#endif \ No newline at end of file +#endif diff --git a/QRCoder/QRCode.cs b/QRCoder/QRCode.cs index e42666b9..74f501bf 100644 --- a/QRCoder/QRCode.cs +++ b/QRCoder/QRCode.cs @@ -9,25 +9,54 @@ namespace QRCoder #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif + /// + /// Represents a QR code generator that outputs QR codes as bitmap images. + /// public class QRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public QRCode() { } + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public QRCode(QRCodeData data) : base(data) { } + /// + /// Creates a black and white bitmap image of the QR code. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// Returns the QR code graphic as a bitmap. public Bitmap GetGraphic(int pixelsPerModule) { return this.GetGraphic(pixelsPerModule, Color.Black, Color.White, true); } + /// + /// Creates a colored bitmap image of the QR code. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HTML hex format. + /// The color of the light modules in HTML hex format. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a bitmap. public Bitmap GetGraphic(int pixelsPerModule, string darkColorHtmlHex, string lightColorHtmlHex, bool drawQuietZones = true) { return this.GetGraphic(pixelsPerModule, ColorTranslator.FromHtml(darkColorHtmlHex), ColorTranslator.FromHtml(lightColorHtmlHex), drawQuietZones); } + /// + /// Creates a colored bitmap image of the QR code. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a bitmap. public Bitmap GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, bool drawQuietZones = true) { var size = (this.QrCodeData.ModuleMatrix.Count - (drawQuietZones ? 0 : 8)) * pixelsPerModule; @@ -61,6 +90,18 @@ public Bitmap GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, return bmp; } + /// + /// Creates a colored bitmap image of the QR code with an optional icon in the center. + /// + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// An optional icon to be placed in the center of the QR code. + /// The size of the icon as a percentage of the QR code size. + /// The width of the border around the icon. + /// Indicates if quiet zones around the QR code should be drawn. + /// The background color of the icon. + /// Returns the QR code graphic as a bitmap. public Bitmap GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, Bitmap? icon = null, int iconSizePercent = 15, int iconBorderWidth = 0, bool drawQuietZones = true, Color? iconBackgroundColor = null) { var size = (this.QrCodeData.ModuleMatrix.Count - (drawQuietZones ? 0 : 8)) * pixelsPerModule; @@ -112,6 +153,12 @@ public Bitmap GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, return bmp; } + /// + /// Creates a rounded rectangle path for drawing. + /// + /// The rectangle for which to create the rounded path. + /// The radius of the corners. + /// Returns the rounded rectangle path. internal GraphicsPath CreateRoundedRectanglePath(RectangleF rect, int cornerRadius) { var roundedRect = new GraphicsPath(); @@ -131,8 +178,28 @@ internal GraphicsPath CreateRoundedRectanglePath(RectangleF rect, int cornerRadi #if NET6_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif + /// + /// Provides static methods for creating bitmap QR codes. + /// public static class QRCodeHelper { + /// + /// Creates a bitmap QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The number of pixels each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules. + /// The color of the light modules. + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// An optional icon to be placed in the center of the QR code. + /// The size of the icon as a percentage of the QR code size. + /// The width of the border around the icon. + /// Indicates if quiet zones around the QR code should be drawn. + /// Returns the QR code graphic as a bitmap. public static Bitmap GetQRCode(string plainText, int pixelsPerModule, Color darkColor, Color lightColor, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, Bitmap? icon = null, int iconSizePercent = 15, int iconBorderWidth = 0, bool drawQuietZones = true) { using (var qrGenerator = new QRCodeGenerator()) @@ -143,4 +210,4 @@ public static Bitmap GetQRCode(string plainText, int pixelsPerModule, Color dark } } -#endif \ No newline at end of file +#endif diff --git a/QRCoder/QRCodeData.cs b/QRCoder/QRCodeData.cs index 5a553458..133221fa 100644 --- a/QRCoder/QRCodeData.cs +++ b/QRCoder/QRCodeData.cs @@ -6,10 +6,20 @@ namespace QRCoder { + /// + /// Represents the data structure of a QR code. + /// public class QRCodeData : IDisposable { + /// + /// Gets or sets the module matrix of the QR code. + /// public List ModuleMatrix { get; set; } + /// + /// Initializes a new instance of the class with the specified version. + /// + /// The version of the QR code. public QRCodeData(int version) { this.Version = version; @@ -19,6 +29,11 @@ public QRCodeData(int version) this.ModuleMatrix.Add(new BitArray(size)); } + /// + /// Initializes a new instance of the class with the specified version and padding option. + /// + /// The version of the QR code. + /// Indicates whether padding should be added to the QR code. public QRCodeData(int version, bool addPadding) { this.Version = version; @@ -28,10 +43,20 @@ public QRCodeData(int version, bool addPadding) this.ModuleMatrix.Add(new BitArray(size)); } + /// + /// Initializes a new instance of the class with raw data from a specified path and compression mode. + /// + /// The path to the raw data file. + /// The compression mode used for the raw data. public QRCodeData(string pathToRawData, Compression compressMode) : this(File.ReadAllBytes(pathToRawData), compressMode) { } + /// + /// Initializes a new instance of the class with raw data and compression mode. + /// + /// The raw data of the QR code. + /// The compression mode used for the raw data. public QRCodeData(byte[] rawData, Compression compressMode) { var bytes = new List(rawData); @@ -98,6 +123,11 @@ public QRCodeData(byte[] rawData, Compression compressMode) } + /// + /// Gets the raw data of the QR code with the specified compression mode. + /// + /// The compression mode used for the raw data. + /// Returns the raw data of the QR code as a byte array. public byte[] GetRawData(Compression compressMode) { var bytes = new List(); @@ -160,18 +190,34 @@ public byte[] GetRawData(Compression compressMode) return rawData; } + /// + /// Saves the raw data of the QR code to a specified file with the specified compression mode. + /// + /// The path to the file where the raw data will be saved. + /// The compression mode used for the raw data. public void SaveRawData(string filePath, Compression compressMode) { File.WriteAllBytes(filePath, GetRawData(compressMode)); } + /// + /// Gets the version of the QR code. + /// public int Version { get; private set; } + /// + /// Gets the number of modules per side from the specified version. + /// + /// The version of the QR code. + /// Returns the number of modules per side. private static int ModulesPerSideFromVersion(int version) { return 21 + (version - 1) * 4; } + /// + /// Releases all resources used by the . + /// public void Dispose() { this.ModuleMatrix = null!; @@ -179,10 +225,22 @@ public void Dispose() } + /// + /// Specifies the compression mode used for the raw data. + /// public enum Compression { + /// + /// No compression. + /// Uncompressed, + /// + /// Deflate compression. + /// Deflate, + /// + /// GZip compression. + /// GZip } } diff --git a/QRCoder/QRCodeGenerator.cs b/QRCoder/QRCodeGenerator.cs index dd7897f0..a3215b38 100644 --- a/QRCoder/QRCodeGenerator.cs +++ b/QRCoder/QRCodeGenerator.cs @@ -11,6 +11,9 @@ namespace QRCoder { + /// + /// Provides functionality to generate QR code data that can be used to create QR code images. + /// public partial class QRCodeGenerator : IDisposable { private static readonly char[] alphanumEncTable = { ' ', '$', '%', '*', '+', '-', '.', '/', ':' }; @@ -1390,6 +1393,7 @@ private static List CreateCapacityTable() return localCapacityTable; } + /// public void Dispose() { // left for back-compat diff --git a/QRCoder/QRCoder.csproj b/QRCoder/QRCoder.csproj index c14e05d9..41d3125d 100644 --- a/QRCoder/QRCoder.csproj +++ b/QRCoder/QRCoder.csproj @@ -9,6 +9,7 @@ false true true + $(WarningsAsErrors);CS1591 enable 9.0 diff --git a/QRCoder/SvgQRCode.cs b/QRCoder/SvgQRCode.cs index c0056794..53026dac 100644 --- a/QRCoder/SvgQRCode.cs +++ b/QRCoder/SvgQRCode.cs @@ -11,19 +11,28 @@ namespace QRCoder { + /// + /// Represents a QR code generator that outputs QR codes as SVG images. + /// public class SvgQRCode : AbstractQRCode, IDisposable { /// - /// Constructor without params to be used in COM Objects connections + /// Initializes a new instance of the class. + /// Constructor without parameters to be used in COM objects connections. /// public SvgQRCode() { } + + /// + /// Initializes a new instance of the class with the specified . + /// + /// generated by the QRCodeGenerator. public SvgQRCode(QRCodeData data) : base(data) { } /// - /// Returns a QR code as SVG string + /// Returns a QR code as an SVG string. /// - /// The pixel size each b/w module is drawn - /// SVG as string + /// The pixel size each dark/light module is drawn. + /// Returns the QR code graphic as an SVG string. public string GetGraphic(int pixelsPerModule) { var viewBox = new Size(pixelsPerModule*this.QrCodeData.ModuleMatrix.Count, pixelsPerModule * this.QrCodeData.ModuleMatrix.Count); @@ -31,15 +40,15 @@ public string GetGraphic(int pixelsPerModule) } /// - /// Returns a QR code as SVG string with custom colors, optional quietzone and logo + /// Returns a QR code as an SVG string with custom colors, optional quiet zones, and an optional logo. /// - /// The pixel size each b/w module is drawn - /// Color of the dark modules - /// Color of the light modules - /// If true a white border is drawn around the whole QR Code - /// Defines if width/height or viewbox should be used for size definition - /// A (optional) logo to be rendered on the code (either Bitmap or SVG) - /// SVG as string + /// The pixel size each dark/light module is drawn. + /// The color of the dark modules. + /// The color of the light modules. + /// If true, a white border is drawn around the entire QR code. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public string GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { var offset = drawQuietZones ? 0 : 4; @@ -49,15 +58,15 @@ public string GetGraphic(int pixelsPerModule, Color darkColor, Color lightColor, } /// - /// Returns a QR code as SVG string with custom colors (in HEX syntax), optional quietzone and logo + /// Returns a QR code as an SVG string with custom colors (in HEX syntax), optional quiet zones, and an optional logo. /// - /// The pixel size each b/w module is drawn - /// The color of the dark/black modules in hex (e.g. #000000) representation - /// The color of the light/white modules in hex (e.g. #ffffff) representation - /// If true a white border is drawn around the whole QR Code - /// Defines if width/height or viewbox should be used for size definition - /// A (optional) logo to be rendered on the code (either Bitmap or SVG) - /// SVG as string + /// The pixel size each dark/light module is drawn. + /// The color of the dark/black modules in HEX format (e.g., #000000). + /// The color of the light/white modules in HEX format (e.g., #ffffff). + /// If true, a white border is drawn around the entire QR code. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public string GetGraphic(int pixelsPerModule, string darkColorHex, string lightColorHex, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { var offset = drawQuietZones ? 0 : 4; @@ -67,43 +76,43 @@ public string GetGraphic(int pixelsPerModule, string darkColorHex, string lightC } /// - /// Returns a QR code as SVG string with optional quietzone and logo + /// Returns a QR code as an SVG string with optional quiet zones and an optional logo. /// - /// The viewbox of the QR code graphic - /// If true a white border is drawn around the whole QR Code - /// Defines if width/height or viewbox should be used for size definition - /// A (optional) logo to be rendered on the code (either Bitmap or SVG) - /// SVG as string + /// The viewBox of the QR code graphic. + /// If true, a white border is drawn around the entire QR code. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public string GetGraphic(Size viewBox, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { return this.GetGraphic(viewBox, Color.Black, Color.White, drawQuietZones, sizingMode, logo); } /// - /// Returns a QR code as SVG string with custom colors and optional quietzone and logo + /// Returns a QR code as an SVG string with custom colors and optional quiet zones and an optional logo. /// - /// The viewbox of the QR code graphic - /// Color of the dark modules - /// Color of the light modules - /// If true a white border is drawn around the whole QR Code - /// Defines if width/height or viewbox should be used for size definition - /// A (optional) logo to be rendered on the code (either Bitmap or SVG) - /// SVG as string + /// The viewBox of the QR code graphic. + /// The color of the dark modules. + /// The color of the light modules. + /// If true, a white border is drawn around the entire QR code. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public string GetGraphic(Size viewBox, Color darkColor, Color lightColor, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { return this.GetGraphic(viewBox, ColorTranslator.ToHtml(Color.FromArgb(darkColor.ToArgb())), ColorTranslator.ToHtml(Color.FromArgb(lightColor.ToArgb())), drawQuietZones, sizingMode, logo); } /// - /// Returns a QR code as SVG string with custom colors (in HEX syntax), optional quietzone and logo + /// Returns a QR code as an SVG string with custom colors (in HEX syntax), optional quiet zones, and an optional logo. /// - /// The viewbox of the QR code graphic - /// The color of the dark/black modules in hex (e.g. #000000) representation - /// The color of the light/white modules in hex (e.g. #ffffff) representation - /// If true a white border is drawn around the whole QR Code - /// Defines if width/height or viewbox should be used for size definition - /// A (optional) logo to be rendered on the code (either Bitmap or SVG) - /// SVG as string + /// The viewBox of the QR code graphic. + /// The color of the dark/black modules in HEX format (e.g., #000000). + /// The color of the light/white modules in HEX format (e.g., #ffffff). + /// If true, a white border is drawn around the entire QR code. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public string GetGraphic(Size viewBox, string darkColorHex, string lightColorHex, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { int offset = drawQuietZones ? 0 : 4; @@ -331,7 +340,6 @@ public SvgLogo(byte[] iconRasterized, int iconSizePercent = 15, bool fillLogoBac /// /// Returns the raw logo's data /// - /// public object GetRawLogo() { return _logoRaw; @@ -341,7 +349,6 @@ public object GetRawLogo() /// Defines, if the logo shall be natively embedded. /// true=native svg embedding, false=embedding via image-tag /// - /// public bool IsEmbedded() { return _isEmbedded; @@ -359,7 +366,6 @@ public MediaType GetMediaType() /// /// Returns the logo as data-uri /// - /// public string GetDataUri() { return $"data:{GetMimeType(_mediaType)};base64,{_logoData}"; @@ -368,7 +374,6 @@ public string GetDataUri() /// /// Returns how much of the QR code should be covered by the logo (in percent) /// - /// public int GetIconSizePercent() { return _iconSizePercent; @@ -377,7 +382,6 @@ public int GetIconSizePercent() /// /// Returns if the background of the logo should be cleaned (no QR modules will be rendered behind the logo) /// - /// public bool FillLogoBackground() { return _fillLogoBackground; @@ -414,8 +418,27 @@ private string GetMimeType(MediaType type) } } + /// + /// Provides static methods for creating SVG QR codes. + /// public static class SvgQRCodeHelper { + /// + /// Creates an SVG QR code with a single function call. + /// + /// The text or payload to be encoded inside the QR code. + /// The pixel size each dark/light module of the QR code will occupy in the final QR code image. + /// The color of the dark modules in HEX format (e.g., #000000). + /// The color of the light modules in HEX format (e.g., #ffffff). + /// The level of error correction data. + /// Specifies whether the generator should be forced to work in UTF-8 mode. + /// Specifies whether the byte-order-mark should be used. + /// Specifies which ECI mode should be used. + /// Sets the fixed QR code target version. + /// Indicates if quiet zones around the QR code should be drawn. + /// Defines whether width/height or viewBox should be used for size definition. + /// An optional logo to be rendered on the code (either Bitmap or SVG). + /// Returns the QR code graphic as an SVG string. public static string GetQRCode(string plainText, int pixelsPerModule, string darkColorHex, string lightColorHex, ECCLevel eccLevel, bool forceUtf8 = false, bool utf8BOM = false, EciMode eciMode = EciMode.Default, int requestedVersion = -1, bool drawQuietZones = true, SizingMode sizingMode = SizingMode.WidthHeightAttribute, SvgLogo? logo = null) { using (var qrGenerator = new QRCodeGenerator()) diff --git a/QRCoderTests/PayloadGeneratorTests.cs b/QRCoderTests/PayloadGeneratorTests.cs index c8af94ca..17931b95 100644 --- a/QRCoderTests/PayloadGeneratorTests.cs +++ b/QRCoderTests/PayloadGeneratorTests.cs @@ -1225,7 +1225,7 @@ public void girocode_generator_should_throw_amount_min_exception() Assert.NotNull(exception); Assert.IsType(exception); - exception.Message.ShouldBe("Amount has to at least 0.01 and must be smaller or equal to 999999999.99."); + exception.Message.ShouldBe("Amount has to be at least 0.01 and must be smaller or equal to 999999999.99."); } @@ -1248,7 +1248,7 @@ public void girocode_generator_should_throw_amount_max_exception() Assert.NotNull(exception); Assert.IsType(exception); - exception.Message.ShouldBe("Amount has to at least 0.01 and must be smaller or equal to 999999999.99."); + exception.Message.ShouldBe("Amount has to be at least 0.01 and must be smaller or equal to 999999999.99."); } @@ -1291,7 +1291,7 @@ public void girocode_generator_should_throw_remittance_unstructured_exception() Assert.NotNull(exception); Assert.IsType(exception); - exception.Message.ShouldBe("Unstructured reference texts have to shorter than 141 chars."); + exception.Message.ShouldBe("Unstructured reference texts have to be shorter than 141 chars."); } [Fact] @@ -1312,7 +1312,7 @@ public void girocode_generator_should_throw_remittance_structured_exception() Assert.NotNull(exception); Assert.IsType(exception); - exception.Message.ShouldBe("Structured reference texts have to shorter than 36 chars."); + exception.Message.ShouldBe("Structured reference texts have to be shorter than 36 chars."); } [Fact] @@ -1333,7 +1333,7 @@ public void girocode_generator_should_throw_usermessage_exception() Assert.NotNull(exception); Assert.IsType(exception); - exception.Message.ShouldBe("Message to the Girocode-User reader texts have to shorter than 71 chars."); + exception.Message.ShouldBe("Message to the Girocode-User reader texts have to be shorter than 71 chars."); } [Fact]