Per Subscription Event Handlers (#120)

hivemq · Jan 23, 2024 · d32fc96 · d32fc96
1 parent afa1115
commit d32fc96
Show file tree

Hide file tree

Showing 26 changed files with 664 additions and 538 deletions.
diff --git a/Documentation/docs/connecting.md b/Documentation/docs/connecting.md
@@ -0,0 +1,80 @@
+---
+sidebar_position: 4
+---
+
+# Connecting to an MQTT Broker
+
+## with Defaults
+
+Without any options given, the `HiveMQClient` will search on `localhost` port 1883 for an unsecured broker.
+
+If you don't have a broker at this location, see the next sections.
+
+```csharp
+using HiveMQtt.Client;
+
+// Connect
+var client = new HiveMQClient();
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+```
+
+## With Options
+
+The `HiveMQClientOptions` class provides a set of options that can be used to configure various aspects of the `HiveMQClient`.
+
+The easiest way to construct this class is to use `HiveMQClientOptionsBuilder`.
+
+```csharp
+var options = new HiveMQClientOptionsBuilder().
+                    WithBroker('candy.x39.eu.hivemq.cloud').
+                    WithPort(8883).
+                    WithUseTLS(true).
+                    Build();
+
+var client = new HiveMQClient(options);
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+```
+
+## `HiveMQClientOptionsBuilder` Reference
+
+To illustrate _each and every possible call_ with `HiveMQClientOptionsBuilder`, see the following example:
+
+```csharp
+using HiveMQtt.MQTT5.Types; // For QualityOfService enum
+
+var options = new HiveMQClientOptionsBuilder()
+    .WithBroker("broker.hivemq.com")
+    .WithPort(1883)
+    .WithClientId("myClientId")
+    .WithAllowInvalidBrokerCertificates(true)
+    .WithUseTls(true)
+    .WithCleanStart(true)
+    .WithKeepAlive(60)
+    .WithAuthenticationMethod("UsernamePassword")
+    .WithAuthenticationData(Encoding.UTF8.GetBytes("authenticationData"))
+    .WithUserProperty("property1", "value1")
+    .WithUserProperties(new Dictionary<string, string> { { "property1", "value1" }, { "property2", "value2" } })
+    .WithLastWill(new LastWillAndTestament {
+                            Topic = "lwt/topic",
+                            PayloadAsString = "LWT message",
+                            QoS = QualityOfService.AtLeastOnceDelivery,
+                            Retain = true })
+    .WithMaximumPacketSize(1024)
+    .WithReceiveMaximum(100)
+    .WithSessionExpiryInterval(3600)
+    .WithUserName("myUserName")
+    .WithPassword("myPassword")
+    .WithPreferIPv6(true)
+    .WithTopicAliasMaximum(10)
+    .WithRequestProblemInformation(true)
+    .WithRequestResponseInformation(true)
+    .Build();
+```
+
+## See Also
+
+* [How to Set a Last Will & Testament](/docs/how-to/set-lwt)
+* [Connect with TLS but allow Invalid TLS Certificates](/docs/how-to/allow-invalid-certs)
+* [Securely Connect to a Broker with Basic Authentication Credentials](/docs/how-to/connect-with-auth)
+* [Custom Client Certificates](/docs/how-to/client-certificates)
+* [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs)
diff --git a/Documentation/docs/events/Reference.md b/Documentation/docs/events/Reference.md
@@ -1,11 +1,14 @@
 ---
 sidebar_position: 1
 ---
-# Reference
+# Event Reference
 
-## List of Supported Events
+This document provides a comprehensive list of events supported by the HiveMQtt client library. These events are categorized into two sections: General and Packet Level.
+
+## General Events
+
+General events are triggered by high-level operations such as connecting, subscribing, unsubscribing, and receiving messages.
 
-### General
 
 | Event         | EventArgs Class          | Event Arguments      |
 | ------------- | ------------------------ | -------------------- |
@@ -17,9 +20,10 @@ sidebar_position: 1
 | AfterUnsubscribe  | `AfterUnsubscribeEventArgs` |  `UnsubscribeResult` |
 | OnMessageReceived | `OnMessageReceivedEventArgs` |  `MQTT5PublishMessage` |
 
-### Packet Level
+## Packet Level Events
+
+Packet level events are triggered by the underlying MQTT packet activity. These events provide a more granular level of control and can be useful for debugging or advanced use cases.
 
-These events happen based on MQTT packet activity.
 
 | Event         | EventArgs Class          | Event Arguments      |
 | ------------- | ------------------------ | -------------------- |

diff --git a/Documentation/docs/events/_category_.json b/Documentation/docs/events/_category_.json
@@ -1,4 +1,4 @@
 {
   "label": "Lifecycle Events",
-  "position": 4
+  "position": 9
 }
diff --git a/Documentation/docs/help.md b/Documentation/docs/help.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 100
 ---
 
 # Getting Help

diff --git a/Documentation/docs/how-to/_category_.json b/Documentation/docs/how-to/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "How To Guides",
-  "position": 4,
+  "position": 10,
   "link": {
     "type": "generated-index",
     "description": "Guides on how to do almost anything with HiveMQtt."

diff --git a/Documentation/docs/how-to/allow-invalid-certs.md b/Documentation/docs/how-to/allow-invalid-certs.md
@@ -1,6 +1,10 @@
-# Connect with TLS but allow Invalid TLS Certificates
+# Connecting with TLS and Allowing Invalid TLS Certificates
 
-Use the `AllowInvalidBrokerCertificates` option in `HiveMQClientOptions` to disable the TLS certificate check upon connect.
+In certain development or testing scenarios, you might need to connect to an MQTT broker that uses TLS but has an invalid or self-signed certificate. The HiveMQtt client library provides an option to disable the TLS certificate check upon connection, which can be useful in these situations.
+
+The `AllowInvalidBrokerCertificates` option in the `HiveMQClientOptions` class allows you to disable the TLS certificate check. 
+
+Here's an example of how to use this option:
 
 ```csharp
 var options = new HiveMQClientOptionsBuilder()
@@ -14,6 +18,14 @@ var client = new HiveMQClient(options);
 var connectResult = await client.ConnectAsync().ConfigureAwait(false);
 ```
 
+In this example, we first create an instance of HiveMQClientOptionsBuilder. We then set the broker address, port, and enable TLS. The WithAllowInvalidBrokerCertificates(true) method call disables the TLS certificate check. Finally, we build the options and use them to create a new HiveMQClient.
+
+:::note
+
+Disabling the TLS certificate check can expose your application to security risks, such as man-in-the-middle attacks. Therefore, this option should only be used in controlled environments for development or testing purposes.
+
+::: 
+
 ## See Also
 
 * [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs)

diff --git a/Documentation/docs/how-to/publish.md b/Documentation/docs/how-to/publish.md
diff --git a/Documentation/docs/how-to/subscribe-multi.md b/Documentation/docs/how-to/subscribe-multi.md
diff --git a/Documentation/docs/how-to/subscribe.md b/Documentation/docs/how-to/subscribe.md