More Examples & Use Fully Qualified Links (#45)

Author: pglombardo

Documentation/Events.md

@@ -1,24 +1,27 @@
 # Events
 
-This client has built in events to allow users to hook into any part of the client.
+This HiveMQ client has a large number of built in events to allow users to hook into any part of the client.
 
-This can be used to modify behavior, monitor activity or extend functionality.
+These events can be used to modify behavior, monitor activity or extend functionality.
 
 ## Examples
 
-### Display Connect Options Prior to Connecting
+The following serves as a few examples on how to utilize the built in event system.
 
-The following serves as an example how to utilize events.  This one simply prints out the HiveMQClientOptions prior to the connect command being sent to the broker.
+### Display Options Prior to Connecting
+
+This one simply prints out the HiveMQClientOptions prior to the connect command being sent to the broker.
 
 ```C#
+using HiveMQtt.Client.Events;
+
 private static void BeforeConnectHandler(object? sender, BeforeConnectEventArgs eventArgs)
 {
-    Assert.NotNull(sender);
     if (sender is not null)
     {
         var client = (HiveMQClient)sender;
         Console.WriteLine("Connecting to Broker with the Options: {}", eventArgs.Options)
-        
+
     }
 }
 
@@ -30,7 +33,92 @@ client.BeforeConnect += BeforeConnectHandler;
 var connectResult = await client.ConnectAsync().ConfigureAwait(false);
 ```
 
-## List of Supported Events 
+### Taking Action After a Subscribe
+
+Suppose you wanted to take some global action after every subscribe call made by the client.
+
+```C#
+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.
+
+```C#
+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
+
+```C#
+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
 
@@ -71,3 +159,7 @@ These events happen based on MQTT packet activity.
 | 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)

Documentation/Examples.md

@@ -1,3 +1,4 @@
+These examples serve to help you get started quickly and easily.  If you want to see another example here, feel free to let us know by [filing an issue](https://github.com/hivemq/hivemq-mqtt-client-dotnet/issues/new/choose).  We'd be happy to help out.
 
 ## How to Wait on an Event
 
@@ -29,7 +30,7 @@ await client.DisconnectAsync().ConfigureAwait(false);
 await taskCompletionSource.Task.WaitAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
 ```
 
-#### Subscribe to Multiple Topics At Once With Varying QoS Levels
+## Subscribe to Multiple Topics At Once With Varying QoS Levels
 
 ```c#
 using HiveMQtt.Client.Options;
@@ -46,3 +47,21 @@ var result = await client.SubscribeAsync(options);
 * `client.Subscriptions` is updated with complete list of subscriptions made up to this point
 * each `Subscription` object has a resulting `ReasonCode` that represents the Subscribe result in `result.Subscriptions[0].ReasonCode`
 
+## Securely Connect to a Broker with Basic Authorization Credentials
+
+```C#
+var options = new HiveMQClientOptions()
+{
+    Host = "b8293h09193b.s1.eu.hivemq.cloud",
+    Port = 8883,
+    UseTLS = true,
+    UserName = "my-username",
+    Password = "my-password",
+};
+
+var client = new HiveMQClient(options);
+var connectResult = await client.ConnectAsync().ConfigureAwait(false);
+```
+## See Also
+
+* HiveMQClient [Events](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Documentation/Events.md)

README.md

@@ -15,7 +15,7 @@ We'd appreciate any feedback you have.  Happy MQTT adventures!
 * **Opensource**: No blackbox code.  Only trusted, tested and reviewed opensource code.
 * **Easy to Use**: Smart defaults, excellent interfaces and intelligent automation makes implementing a breeze.
 * **MQTT v5.0 compatible**: Backported versions 3.1.1 & 3.0 coming soon!
-* **Extensive Event System**: Hook into all parts of the client down to the packet level with [built in events](./Documentation/Events.md).
+* **Extensive Event System**: Hook into all parts of the client down to the packet level with [built in events](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Documentation/Events.md).
 * **Globally Compatible**: Built to be a fully compliant client compatible with all reputable MQTT brokers.
 * **Actively Maintained**: Built by the MQTT professionals that built HiveMQ (and do this for a living).
 * **Extensively Documented**: What good is it without excellent documentation?
@@ -98,7 +98,7 @@ await client.PublishAsync(
                 ).ConfigureAwait(false);
 ```
 
-For more examples that you can easily copy/paste, see our [Examples](./Examples/).
+For more examples that you can easily copy/paste, see our [Examples](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Documentation/Examples.md).
 
 ## Other MQTT Clients