diff --git a/Documentation/docs/connecting.md b/Documentation/docs/connecting.md index bfbe3aab..5715a14e 100644 --- a/Documentation/docs/connecting.md +++ b/Documentation/docs/connecting.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 40 --- # Connecting to an MQTT Broker diff --git a/Documentation/docs/events/_category_.json b/Documentation/docs/events/_category_.json index 5e3b88b0..23448f18 100644 --- a/Documentation/docs/events/_category_.json +++ b/Documentation/docs/events/_category_.json @@ -1,4 +1,4 @@ { "label": "Lifecycle Events", - "position": 9 + "position": 70 } diff --git a/Documentation/docs/how-to/_category_.json b/Documentation/docs/how-to/_category_.json index 6f957d4e..0e29ab78 100644 --- a/Documentation/docs/how-to/_category_.json +++ b/Documentation/docs/how-to/_category_.json @@ -1,6 +1,6 @@ { "label": "How To Guides", - "position": 10, + "position": 80, "link": { "type": "generated-index", "description": "Guides on how to do almost anything with HiveMQtt." diff --git a/Documentation/docs/intro.md b/Documentation/docs/intro.md index cc7f0707..7558a816 100644 --- a/Documentation/docs/intro.md +++ b/Documentation/docs/intro.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 10 --- # The MQTT Client diff --git a/Documentation/docs/namespaces.md b/Documentation/docs/namespaces.md index 2707eff4..c500d79a 100644 --- a/Documentation/docs/namespaces.md +++ b/Documentation/docs/namespaces.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 30 --- # Namespaces diff --git a/Documentation/docs/publishing.md b/Documentation/docs/publishing.md index 37cce853..c3376468 100644 --- a/Documentation/docs/publishing.md +++ b/Documentation/docs/publishing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 60 --- # Publishing Messages diff --git a/Documentation/docs/quickstart.md b/Documentation/docs/quickstart.md index 67c4ea33..975051f5 100644 --- a/Documentation/docs/quickstart.md +++ b/Documentation/docs/quickstart.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 20 --- # Quickstart diff --git a/Documentation/docs/reference/_category_.json b/Documentation/docs/reference/_category_.json new file mode 100644 index 00000000..18b56fb7 --- /dev/null +++ b/Documentation/docs/reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Reference", + "position": 85, + "link": { + "type": "generated-index", + "description": "Comprehensive reference guide." + } +} diff --git a/Documentation/docs/reference/client_options.md b/Documentation/docs/reference/client_options.md new file mode 100644 index 00000000..239deb3f --- /dev/null +++ b/Documentation/docs/reference/client_options.md @@ -0,0 +1,136 @@ +--- +sidebar_position: 45 +--- +# HiveMQClientOptions + +The `HiveMQClientOptions` class provides options for configuring the HiveMQ MQTT client. + +## Properties + +### `ClientId` +---------------- + +* Type: `string?` +* Description: The client identifier to be used in the Client. Will be set automatically if not specified. + +### `Host` +---------------- + +* Type: `string` +* Description: The IP address or DNS hostname of the MQTT broker to connect to. + +### `Port` +---------------- + +* Type: `int` +* Description: The port to connect to on the MQTT broker. + +### `PreferIPv6` +---------------- + +* Type: `bool` +* Description: When resolving a DNS hostname in the `Host` property, prefer IPv6 addresses over IPv4 addresses. + +### `KeepAlive` +---------------- + +* Type: `int` +* Description: The maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one MQTT Control Packet and the point it starts sending the next. + +### `CleanStart` +---------------- + +* Type: `bool` +* Description: Specifies whether the Connection starts a new Session or is a continuation of an existing Session. + +### `UserName` and `Password` +------------------------- + +* Type: `string?` +* Description: The MQTT CONNECT packet supports basic authentication of a Network Connection using the User Name and Password fields. While these fields are named for a simple password authentication, they can be used to carry other forms of authentication such as passing a token as the Password. + +### `SessionExpiryInterval` +------------------------- + +* Type: `long` +* Description: The session expiration interval in use by the MQTT broker. + +### `ClientReceiveMaximum` +------------------------- + +* Type: `int?` +* Description: The maximum number of QoS 1 and QoS 2 publications that this MQTT client is willing to process concurrently. + +### `ClientMaximumPacketSize` +------------------------- + +* Type: `long?` +* Description: The maximum packet size that the MQTT client is willing to accept. + +### `ClientTopicAliasMaximum` +------------------------- + +* Type: `int?` +* Description: The highest value that the Client will accept as a Topic Alias sent by the Server. + +### `RequestResponseInformation` and `RequestProblemInformation` +------------------------- + +* Type: `bool?` +* Description: The Request Response Information flag and the Request Problem Information flag. + +### `UserProperties` +---------------- + +* Type: `Dictionary` +* Description: A dictionary containing the User Properties returned by the MQTT broker. + +### `AuthenticationMethod` and `AuthenticationData` +------------------------- + +* Type: `string?` and `byte[]?` +* Description: The authentication method and data used for extended authentication. + +### `UseTLS` +---------------- + +* Type: `bool` +* Description: Whether the MQTT client should use TLS. + +### `ClientCertificates` +---------------- + +* Type: `X509CertificateCollection` +* Description: The collection of client X509 certificates. + +### `AllowInvalidBrokerCertificates` +------------------------- + +* Type: `bool` +* Description: Whether the MQTT client should allow invalid broker TLS certificates. + +### `LastWillAndTestament` +------------------------- + +* Type: `LastWillAndTestament?` +* Description: Whether a Last Will and Testament should be used in the Connect. + +### `ConnectTimeoutInMs` +------------------------- + +* Type: `int` +* Description: The time in milliseconds to wait for a connection to be established. + +## Constructors +--------------- + +The `HiveMQClientOptions` class has a default constructor that initializes all properties to their default values. + +## Methods +--------- + +### `Validate()` + +* Return: `void` +* Throws: `HiveMQttClientException` on error +* Validate that the options specified in this class are all sane and valid. diff --git a/Documentation/docs/reference/client_options_builder.md b/Documentation/docs/reference/client_options_builder.md new file mode 100644 index 00000000..85b2fd11 --- /dev/null +++ b/Documentation/docs/reference/client_options_builder.md @@ -0,0 +1,217 @@ +# HiveMQClientOptionsBuilder + +The `HiveMQClientOptionsBuilder` class is a builder pattern implementation that provides a convenient way to construct `HiveMQClientOptions` objects for configuring HiveMQClient connections to an MQTT broker. + +## Methods + +### `WithBroker(string broker)` + +Sets the address of the broker to connect to. + +**Description:** The broker address can be an IPv4 or IPv6 address, a hostname, or a URL. This value is used to establish the connection to the MQTT broker. + +**Example:** `WithBroker("mqtt.example.com")` + +### `WithPort(int port)` + +Sets the port to connect to. + +**Description:** The port number is used to establish the connection to the MQTT broker. The default port number for MQTT is 1883. + +**Example:** `WithPort(1883)` + +### `WithClientId(string clientId)` + +Sets the client identifier. + +**Description:** The client identifier is a unique identifier for the client connecting to the MQTT broker. It is used to identify the client and maintain session state. + +**Example:** `WithClientId("myClientId")` + +### `WithAllowInvalidBrokerCertificates(bool allowInvalidCertificates)` + +Sets whether to allow invalid broker certificates. + +**Description:** This flag allows the client to ignore invalid broker certificates. This is useful for testing purposes, but should not be used in production. + +**Example:** `WithAllowInvalidBrokerCertificates(true)` + +### `WithUseTls(bool useTls)` + +Sets whether to use TLS when connecting to the broker. + +**Description:** This flag enables or disables the use of Transport Layer Security (TLS) when connecting to the MQTT broker. + +**Example:** `WithUseTls(true)` + +### `WithClientCertificate(X509Certificate2 clientCertificate)` + +Adds a client X.509 certificate to be used for client authentication. + +**Description:** This method adds a client X.509 certificate to be used for client authentication. The certificate is used to verify the client's identity. + +**Example:** `WithClientCertificate(new X509Certificate2("path/to/certificate.pfx", "password"))` + +### `WithClientCertificates(List clientCertificates)` + +Adds a list of client X.509 certificates to be used for client authentication. + +**Description:** This method adds a list of client X.509 certificates to be used for client authentication. The certificates are used to verify the client's identity. + +**Example:** `WithClientCertificates(new List { new X509Certificate2("path/to/certificate1.pfx", "password"), new X509Certificate2("path/to/certificate2.pfx", "password") })` + +### `WithClientCertificate(string clientCertificatePath, string? password = null)` + +Adds a client X.509 certificate to be used for client authentication from a file. + +**Description:** This method adds a client X.509 certificate to be used for client authentication from a file. The certificate is used to verify the client's identity. + +**Example:** `WithClientCertificate("path/to/certificate.pfx", "password")` + +### `WithCleanStart(bool cleanStart)` + +Sets whether to use a clean start. + +**Description:** This flag indicates whether to use a clean start when connecting to the MQTT broker. A clean start means that the broker will discard any previous session state and start a new session. + +**Example:** `WithCleanStart(true)` + +### `WithKeepAlive(int keepAlive)` + +Sets the keep alive period. + +**Description:** The keep alive period is the time interval between two control packets (PINGREQ and PINGRESP) sent by the client to the broker. This value is used to detect network failures and maintain the connection. + +**Example:** `WithKeepAlive(60)` + +### `WithAuthenticationMethod(string method)` + +Sets the authentication method. + +**Description:** The authentication method is used to authenticate the client with the MQTT broker. The available authentication methods are "username_password" and "none". + +**Example:** `WithAuthenticationMethod("username_password")` + +### `WithAuthenticationData(byte[] data)` + +Sets the authentication data. + +**Description:** The authentication data is used to authenticate the client with the MQTT broker. The format and interpretation of the authentication data depend on the chosen authentication method. + +**Example:** `WithAuthenticationData(Encoding.UTF8.GetBytes("username_password"))` + +### `WithUserProperty(string key, string value)` + +Adds a user property to be sent in the connect call. + +**Description:** User properties are custom key-value pairs that can be sent in the CONNECT packet. They are used to provide additional metadata or application-specific information. + +**Example:** `WithUserProperty("property1", "value1")` + +### `WithUserProperties(Dictionary properties)` + +Adds a dictionary of user properties to be sent in the connect call. + +**Description:** This method adds a dictionary of user properties to be sent in the connect call. The dictionary is used to provide additional metadata or application-specific information. + +**Example:** `WithUserProperties(new Dictionary { { "property1", "value1" }, { "property2", "value2" } })` + +### `WithLastWillAndTestament(LastWillAndTestament lwt)` + +Sets the last will and testament. + +**Description:** The last will and testament is a message that is published by the broker when the client disconnects unexpectedly. It is used to notify other clients of the client's disconnection. + +**Example:** `WithLastWillAndTestament(new LastWillAndTestament("topic", "message", MqttQualityOfServiceLevel.AtLeastOnce, true))` + +### `WithMaximumPacketSize(int maximumPacketSize)` + +Sets the maximum packet size. + +**Description:** The maximum packet size is the maximum size of an MQTT packet that the client is willing to receive from the broker. This value is used to prevent the client from receiving oversized packets. + +**Example:** `WithMaximumPacketSize(1024)` + +### `WithReceiveMaximum(int receiveMaximum)` + +Sets the receive maximum. + +**Description:** The receive maximum is the maximum number of QoS 1 and QoS 2 messages that the client is willing to receive simultaneously from the broker. This value is used to prevent the client from receiving too many messages at once. + +**Example:** `WithReceiveMaximum(100)` + +### `WithSessionExpiryInterval(int sessionExpiryInterval)` + +Sets the session expiry interval. + +**Description:** The session expiry interval is the maximum duration for which the broker maintains the client's session state. This value is used to control the lifespan of the client's session on the broker. + +**Example:** `WithSessionExpiryInterval(3600)` + +### `WithUserName(string username)` + +Sets the username. + +**Description:** The username is used to authenticate the client with the MQTT broker. It is used in conjunction with the password to verify the client's identity. + +**Example:** `WithUserName("myUsername")` + +### `WithPassword(string password)` + +Sets the password. + +**Description:** The password is used to authenticate the client with the MQTT broker. It is used in conjunction with the username to verify the client's identity. + +**Example:** `WithPassword("myPassword")` + +### `WithPreferIPv6(bool preferIPv6)` + +Sets whether to prefer IPv6. + +**Description:** This flag indicates whether to prefer IPv6 over IPv4 when connecting to the MQTT broker. + +**Example:** `WithPreferIPv6(true)` + +### `WithTopicAliasMaximum(int topicAliasMaximum)` + +Sets the topic alias maximum. + +**Description:** The topic alias maximum is the maximum number of topic aliases that the client is willing to use in subsequent MQTT messages. + +**Example:** `WithTopicAliasMaximum(10)` + +### `WithRequestResponseInformation(bool requestResponseInformation)` + +Sets whether to request response information. + +**Description:** This flag indicates whether to request response information from the broker. The response information includes the response code, reason string, and user properties. + +**Example:** `WithRequestResponseInformation(true)` + +### `WithRequestProblemInformation(bool requestProblemInformation)` + +Sets whether to request problem information. + +**Description:** This flag indicates whether to request problem information from the broker. The problem information includes the error code, reason string, and user properties. + +**Example:** `WithRequestProblemInformation(true)` + +### `Build()` + +Builds the `HiveMQClientOptions` instance. + +**Description:** This method builds the `HiveMQClientOptions` instance based on the configured options. + +**Example:** `HiveMQClientOptions options = new HiveMQClientOptionsBuilder().WithBroker("mqtt.example.com").WithPort(1883).Build();` + +## Properties + +### `HiveMQClientOptions options` + +The `HiveMQClientOptions` instance being built. + +## Notes + +* The `HiveMQClientOptionsBuilder` class is a fluent API that allows you to construct `HiveMQClientOptions` objects in a fluent manner. +* The `HiveMQClientOptions` instance is built by calling the `Build()` method. +* The `HiveMQClientOptions` instance can be used to configure the HiveMQClient connection to an MQTT broker. diff --git a/Documentation/docs/reference/disconnect_options.md b/Documentation/docs/reference/disconnect_options.md new file mode 100644 index 00000000..b51792b3 --- /dev/null +++ b/Documentation/docs/reference/disconnect_options.md @@ -0,0 +1,30 @@ +# DisconnectOptions + +The `DisconnectOptions` class provides options for a disconnect call made with `DisconnectAsync`. + +## Constructors + +* `DisconnectOptions()`: Initializes a new instance of the `DisconnectOptions` class with defaults. + +## Properties + +* `ReasonCode`: Gets or sets the reason code for the disconnection. The default value is `NormalDisconnection`. + + Possible values are details in [DisconnectReasonCode enum](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/ReasonCodes/DisconnectReasonCode.cs). +* `SessionExpiry`: Gets or sets the session expiry in seconds. This sets the expiration for the session to the indicated value. + + Example: `SessionExpiry = 3600` sets the session to expire in 1 hour. +* `ReasonString`: Gets or sets the reason string for the disconnection. This is a human-readable string used for diagnostics only. + + Example: `ReasonString = "Device power save mode."` +* `UserProperties`: Gets or sets the user properties for the disconnection. This is a dictionary of key-value pairs. + + Example: `UserProperties = new Dictionary { { "device-id", "xrw02k-224a" }, { "TZ", "CEST" } }` sets the user properties to include in the disconnect call. + +## Examples + +```csharp +DisconnectOptions disconnectOptions = new DisconnectOptions(); +disconnectOptions.ReasonCode = DisconnectReasonCode.NormalDisconnection; +disconnectOptions.SessionExpiry = 3600; +disconnectOptions.ReasonString = "Device power save mode"; +disconnectOptions.UserProperties = new Dictionary { { "device-id", "xrw02k-224a" }, { "TZ", "CEST" } }; + +await client.DisconnectAsync(disconnectOptions); +``` diff --git a/Documentation/docs/subscribing.md b/Documentation/docs/subscribing.md index 32d871df..4c6deb8b 100644 --- a/Documentation/docs/subscribing.md +++ b/Documentation/docs/subscribing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 50 --- # Subscribing to Topics