Update Documentation

hivemq · Dec 19, 2023 · d8c97b9 · d8c97b9
1 parent 051d78f
commit d8c97b9
Show file tree

Hide file tree

Showing 6 changed files with 220 additions and 168 deletions.
diff --git a/Documentation/docs/events/Events.md b/Documentation/docs/events/Events.md
@@ -1,165 +1,7 @@
-# Events
+# Lifecycle Events
 
-This HiveMQ client has a large number of built in events to allow users to hook into any part of the client.
+The HiveMQ client offers a comprehensive set of built-in lifecycle events that empower users to seamlessly integrate with every aspect of the client's operation. These events serve as hooks, enabling developers to customize behavior, closely monitor activity, and extend the functionality of the client to suit their specific requirements.
 
-These events can be used to modify behavior, monitor activity or extend functionality.
+By leveraging these events, developers can dynamically modify the client's behavior at various stages of its lifecycle. Whether it's intercepting incoming or outgoing messages, performing custom authentication or authorization logic, or implementing advanced monitoring and logging capabilities, the event system provides a powerful mechanism for fine-grained control and extensibility.
 
-## Examples
-
-The following serves as a few examples on how to utilize the built in event system.
-
-### Display Options Prior to Connecting
-
-This one simply prints out the HiveMQClientOptions prior to the connect command being sent to the broker.
-
-```csharp
-using HiveMQtt.Client.Events;
-
-private static void BeforeConnectHandler(object? sender, BeforeConnectEventArgs eventArgs)
-{
-    if (sender is not null)
-    {
-        var client = (HiveMQClient)sender;
-        Console.WriteLine("Connecting to Broker with the Options: {}", eventArgs.Options)
-
-    }
-}
-
-// Later...
-
-var client = new HiveMQClient();
-
-client.BeforeConnect += BeforeConnectHandler;
-var connectResult = await client.ConnectAsync().ConfigureAwait(false);
-```
-
-### Taking Action After a Subscribe
-
-Suppose you wanted to take some global action after every subscribe call made by the client.
-
-```csharp
-using HiveMQtt.Client.Events;
-
-private static void AfterSubscribeHandler(object? sender, AfterSubscribeEventArgs eventArgs)
-{
-    if (sender is not null)
-    {
-        var client = (HiveMQClient)sender;
-
-        // The result of the subscribe call
-        // eventArgs.SubcribeResult
-
-    }
-}
-
-// Later...
-
-var client = new HiveMQClient();
-
-client.BeforeConnect += BeforeConnectHandler;
-var connectResult = await client.ConnectAsync().ConfigureAwait(false);
-var subscribeResult = await client.SubscribeAsync("district/9/level", MQTT5.Types.QualityOfService.ExactlyOnceDelivery).ConfigureAwait(false);
-```
-
-### Monitoring outgoing Publish Packets
-
-The following can be used to monitor when publish packets are transmitted from the client.  A potential debug vector in application development.
-
-```csharp
-using HiveMQtt.Client.Events;
-
-private static void OnPublishSentHandler(object? sender, OnPublishSentEventArgs eventArgs)
-{
-    if (sender is not null)
-    {
-        var client = (HiveMQClient)sender;
-
-        // The transmitted MQTT Publish packet
-        // eventArgs.PublishPacket
-
-        // and the MQTT5PublishMessage
-        // eventArgs.PublishPacket.Message
-
-    }
-}
-
-// Later...
-
-var client = new HiveMQClient();
-var connectResult = await client.ConnectAsync().ConfigureAwait(false);
-
-client.OnPublishSent += OnPublishSentHandler;
-
-var result = await client.PublishAsync("district/7/count", "82", MQTT5.Types.QualityOfService.AtLeastOnceDelivery).ConfigureAwait(false);
-```
-
-### Monitoring Subscribe Response Packets (SUBACK)
-
-The following can be used to monitor SubAck responses from the broker
-
-```csharp
-using HiveMQtt.Client.Events;
-
-private static void OnSubAckReceivedHandler(object? sender, OnSubAckReceivedEventArgs eventArgs)
-{
-    if (sender is not null)
-    {
-        var client = (HiveMQClient)sender;
-
-        // The received SubAck packet
-        // eventArgs.SubAckPacket
-    }
-}
-
-// Later...
-
-var client = new HiveMQClient();
-var connectResult = await client.ConnectAsync().ConfigureAwait(false);
-var subResult = await client.SubscribeAsync("district/9/level", MQTT5.Types.QualityOfService.ExactlyOnceDelivery).ConfigureAwait(false);
-```
-
-## List of Supported Events
-
-### General
-
-| Event         | EventArgs Class          | Event Arguments      |
-| ------------- | ------------------------ | -------------------- |
-| BeforeConnect | `BeforeConnectEventArgs` | `HiveMQClientOptions`  |
-| AfterConnect  | `AfterConnectEventArgs` | `ConnectResult` |
-| BeforeSubscribe | `BeforeSubscribeEventArgs` | `SubscribeOptions`  |
-| AfterSubscribe  | `AfterSubscribeEventArgs` |  `SubscribeResult` |
-| BeforeUnsubscribe | `BeforeUnsubscribeEventArgs` | `UnsubscribeOptions`  |
-| AfterUnsubscribe  | `AfterUnsubscribeEventArgs` |  `UnsubscribeResult` |
-| OnMessageReceived | `OnMessageReceivedEventArgs` |  `MQTT5PublishMessage` |
-
-### Packet Level
-
-These events happen based on MQTT packet activity.
-
-| Event         | EventArgs Class          | Event Arguments      |
-| ------------- | ------------------------ | -------------------- |
-| OnConnectSent        | `OnConnectSentEventArgs`     |  `ConnectPacket` |
-| OnConnAckReceived    | `OnConnAckReceivedEventArgs` |  `ConnAckPacket` |
-| OnConnectSent        | `OnConnectSentEventArgs`     |  `ConnectPacket` |
-| OnDisconnectReceived | `OnDisconnectReceivedEventArgs` |  `DisconnectPacket` |
-| OnDisconnectSent     | `OnDisconnectSentEventArgs`  |  `DisconnectPacket` |
-| OnPingReqSent        | `OnPingReqSentEventArgs`     |  `PingReqPacket` |
-| OnPingRespReceived   | `OnPingRespReceivedEventArgs` |  `PingRespPacket` |
-| OnPublishSent        | `OnPublishSentEventArgs`     |  `PublishPacket` |
-| OnPublishReceived    | `OnPublishReceivedEventArgs` |  `PublishPacket` |
-| OnPubAckSent         | `OnPubAckSentEventArgs`      |  `PubAckPacket` |
-| OnPubAckReceived     | `OnPubAckReceivedEventArgs` |  `PubAckPacket` |
-| OnPubRecSent         | `OnPubRecSentEventArgs`     |  `PubRecPacket` |
-| OnPubRecReceived     | `OnPubRecReceivedEventArgs` |  `PubRecPacket` |
-| OnPubRelSent         | `OnPubRelSentEventArgs`     |  `PubRelPacket` |
-| OnPubRelReceived     | `OnPubRelReceivedEventArgs` |  `PubRelPacket` |
-| OnPubCompSent        | `OnPubCompSentEventArgs`    |  `PubCompPacket` |
-| OnPubCompReceived    | `OnPubCompReceivedEventArgs` |  `PubCompPacket` |
-| OnSubscribeSent      | `OnSubscribeSentEventArgs`    |  `SubscribePacket` |
-| OnSubAckSent         | `OnSubAckSentEventArgs`    |  `SubAckPacket` |
-| OnUnsubscribeSent    | `OnUnsubscribeSentEventArgs`    |  `UnsubscribePacket` |
-| OnUnsubAckSent       | `OnUnsubAckSentEventArgs`    |  `UnsubAckPacket` |
-
-# See Also
-
-* [Examples](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Documentation/Examples.md)
+These events cover a wide range of scenarios, including connection establishment and termination, message publishing and reception, subscription management, error handling, and more. By tapping into these events, developers can seamlessly integrate their own code and business logic into the client's workflow, enabling them to build robust and tailored MQTT applications that align perfectly with their unique use cases.
diff --git a/Documentation/docs/events/Examples.md b/Documentation/docs/events/Examples.md
@@ -0,0 +1,117 @@
+---
+sidebar_position: 2
+---
+# Usage Examples
+
+The following serves as a few examples on how to utilize the built in event system.
+
+## Display Options Prior to Connecting
+
+This example simply prints out the `HiveMQClientOptions` prior to the connect command being sent to the broker.
+
+```csharp
+using HiveMQtt.Client.Events;
+
+private static void BeforeConnectHandler(object? sender, BeforeConnectEventArgs eventArgs)
+{
+    if (sender is not null)
+    {
+        var client = (HiveMQClient)sender;
+        Console.WriteLine("Connecting to Broker with the Options: {}", eventArgs.Options)
+
+    }
+}
+
+// Later...
+
+var client = new HiveMQClient();
+
+client.BeforeConnect += BeforeConnectHandler;
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+```
+
+## Taking Action After a Subscribe
+
+Suppose you wanted to take some global action after every subscribe call made by the client.  This example
+illustrates the steps required.
+
+```csharp
+using HiveMQtt.Client.Events;
+
+private static void AfterSubscribeHandler(object? sender, AfterSubscribeEventArgs eventArgs)
+{
+    if (sender is not null)
+    {
+        var client = (HiveMQClient)sender;
+
+        // The result of the subscribe call
+        // eventArgs.SubcribeResult
+
+    }
+}
+
+// Later...
+
+var client = new HiveMQClient();
+
+client.BeforeConnect += BeforeConnectHandler;
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+var subscribeResult = await client.SubscribeAsync("district/9/level", MQTT5.Types.QualityOfService.ExactlyOnceDelivery).ConfigureAwait(false);
+```
+
+## Monitoring outgoing Publish Packets
+
+The following can be used to monitor when publish packets are transmitted from the client.  A potential debug vector in application development.
+
+```csharp
+using HiveMQtt.Client.Events;
+
+private static void OnPublishSentHandler(object? sender, OnPublishSentEventArgs eventArgs)
+{
+    if (sender is not null)
+    {
+        var client = (HiveMQClient)sender;
+
+        // The transmitted MQTT Publish packet
+        // eventArgs.PublishPacket
+
+        // and the MQTT5PublishMessage
+        // eventArgs.PublishPacket.Message
+
+    }
+}
+
+// Later...
+
+var client = new HiveMQClient();
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+
+client.OnPublishSent += OnPublishSentHandler;
+
+var result = await client.PublishAsync("district/7/count", "82", MQTT5.Types.QualityOfService.AtLeastOnceDelivery).ConfigureAwait(false);
+```
+
+## Monitoring Subscribe Response Packets (SUBACK)
+
+The following can be used to monitor SubAck responses from the broker
+
+```csharp
+using HiveMQtt.Client.Events;
+
+private static void OnSubAckReceivedHandler(object? sender, OnSubAckReceivedEventArgs eventArgs)
+{
+    if (sender is not null)
+    {
+        var client = (HiveMQClient)sender;
+
+        // The received SubAck packet
+        // eventArgs.SubAckPacket
+    }
+}
+
+// Later...
+
+var client = new HiveMQClient();
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+var subResult = await client.SubscribeAsync("district/9/level", MQTT5.Types.QualityOfService.ExactlyOnceDelivery).ConfigureAwait(false);
+```
diff --git a/Documentation/docs/events/Reference.md b/Documentation/docs/events/Reference.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 1
+---
+# Reference
+
+## List of Supported Events
+
+### General
+
+| Event         | EventArgs Class          | Event Arguments      |
+| ------------- | ------------------------ | -------------------- |
+| BeforeConnect | `BeforeConnectEventArgs` | `HiveMQClientOptions`  |
+| AfterConnect  | `AfterConnectEventArgs` | `ConnectResult` |
+| BeforeSubscribe | `BeforeSubscribeEventArgs` | `SubscribeOptions`  |
+| AfterSubscribe  | `AfterSubscribeEventArgs` |  `SubscribeResult` |
+| BeforeUnsubscribe | `BeforeUnsubscribeEventArgs` | `UnsubscribeOptions`  |
+| AfterUnsubscribe  | `AfterUnsubscribeEventArgs` |  `UnsubscribeResult` |
+| OnMessageReceived | `OnMessageReceivedEventArgs` |  `MQTT5PublishMessage` |
+
+### Packet Level
+
+These events happen based on MQTT packet activity.
+
+| Event         | EventArgs Class          | Event Arguments      |
+| ------------- | ------------------------ | -------------------- |
+| OnConnectSent        | `OnConnectSentEventArgs`     |  `ConnectPacket` |
+| OnConnAckReceived    | `OnConnAckReceivedEventArgs` |  `ConnAckPacket` |
+| OnConnectSent        | `OnConnectSentEventArgs`     |  `ConnectPacket` |
+| OnDisconnectReceived | `OnDisconnectReceivedEventArgs` |  `DisconnectPacket` |
+| OnDisconnectSent     | `OnDisconnectSentEventArgs`  |  `DisconnectPacket` |
+| OnPingReqSent        | `OnPingReqSentEventArgs`     |  `PingReqPacket` |
+| OnPingRespReceived   | `OnPingRespReceivedEventArgs` |  `PingRespPacket` |
+| OnPublishSent        | `OnPublishSentEventArgs`     |  `PublishPacket` |
+| OnPublishReceived    | `OnPublishReceivedEventArgs` |  `PublishPacket` |
+| OnPubAckSent         | `OnPubAckSentEventArgs`      |  `PubAckPacket` |
+| OnPubAckReceived     | `OnPubAckReceivedEventArgs` |  `PubAckPacket` |
+| OnPubRecSent         | `OnPubRecSentEventArgs`     |  `PubRecPacket` |
+| OnPubRecReceived     | `OnPubRecReceivedEventArgs` |  `PubRecPacket` |
+| OnPubRelSent         | `OnPubRelSentEventArgs`     |  `PubRelPacket` |
+| OnPubRelReceived     | `OnPubRelReceivedEventArgs` |  `PubRelPacket` |
+| OnPubCompSent        | `OnPubCompSentEventArgs`    |  `PubCompPacket` |
+| OnPubCompReceived    | `OnPubCompReceivedEventArgs` |  `PubCompPacket` |
+| OnSubscribeSent      | `OnSubscribeSentEventArgs`    |  `SubscribePacket` |
+| OnSubAckSent         | `OnSubAckSentEventArgs`    |  `SubAckPacket` |
+| OnUnsubscribeSent    | `OnUnsubscribeSentEventArgs`    |  `UnsubscribePacket` |
+| OnUnsubAckSent       | `OnUnsubAckSentEventArgs`    |  `UnsubAckPacket` |
diff --git a/Documentation/docs/events/_category_.json b/Documentation/docs/events/_category_.json
@@ -1,8 +1,4 @@
 {
   "label": "Lifecycle Events",
-  "position": 3,
-  "link": {
-    "type": "generated-index",
-    "description": "Events Reference for HiveMQtt."
-  }
+  "position": 4
 }
diff --git a/Documentation/docs/how-to/publish.md b/Documentation/docs/how-to/publish.md
@@ -7,7 +7,7 @@ The simple way to publish a message is to use the following API:
 ```csharp
 await client.PublishAsync(
                 "core/dynamic_graph/entity/227489", // Topic to publish to
-                "{'2023': '👍'}"                    // Message to publish
+                "{'2023': '👍'}",                   // Message to publish
                 QualityOfService.AtMostOnceDelivery
                 ).ConfigureAwait(false);
 
@@ -43,6 +43,23 @@ var result = await client.PublishAsync(message);
 
 For the full details, see the source code on [MQTT5PublishMessage](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/MQTT5PublishMessage.cs).
 
+# PublishMessageBuilder
+
+The `PublishMessageBuilder` class provides a convenient way to construct MQTT publish messages with various options and properties. It allows you to customize the topic, payload, quality of service (QoS) level, retain flag, and other attributes of the message.
+
+```csharp
+var publishMessage = new PublishMessageBuilder().
+                            WithTopic("topic1/example").
+                            WithPayload("{'HiveMQ': '👍'}").
+                            WithContentType("application/json")
+                            WithResponseTopic("response/topic")
+                            Build();
+
+await client.PublishAsync(publishMessage).ConfigureAwait(false);
+```
+
+By using `PublishMessageBuilder`, you can easily construct MQTT publish messages with the desired properties and options. It provides a fluent and intuitive way to customize the topic, payload, QoS level, retain flag, and other attributes of the message.
+
 # Publish Return Value: `PublishResult`
 
 The `PublishAsync` method returns a `PublishResult` object.