From 2047f445548a1c52e0d3942716da8af464812d39 Mon Sep 17 00:00:00 2001 From: SeppPenner Date: Sun, 3 Jan 2021 21:46:53 +0100 Subject: [PATCH 1/5] Added client documentation. --- .../IManagedMqttClient.cs | 71 ++++++- .../Connecting/IMqttClientConnectedHandler.cs | 5 + .../MqttClientAuthenticateResult.cs | 68 +++++++ .../MqttClientConnectedEventArgs.cs | 4 + .../IMqttClientDisconnectedHandler.cs | 5 + .../MqttClientDisconnectOptions.cs | 8 + .../MqttClientDisconnectedEventArgs.cs | 14 ++ ...ttExtendedAuthenticationExchangeHandler.cs | 5 + ...ttExtendedAuthenticationExchangeContext.cs | 26 +++ .../MqttExtendedAuthenticationExchangeData.cs | 21 ++ Source/MQTTnet/Client/IMqttClient.cs | 56 ++++++ Source/MQTTnet/Client/IMqttClientFactory.cs | 48 ++++- .../Client/Options/IMqttClientOptions.cs | 96 +++++++++ ...entCertificateValidationCallbackContext.cs | 12 ++ .../Client/Options/MqttClientOptions.cs | 94 +++++++++ .../Options/MqttClientOptionsBuilder.cs | 167 ++++++++++++++++ .../Publishing/MqttClientPublishResult.cs | 18 ++ .../IMqttApplicationMessageReceivedHandler.cs | 5 + .../Subscribing/MqttClientSubscribeOptions.cs | 18 ++ .../MqttClientSubscribeOptionsBuilder.cs | 41 +++- .../MqttClientSubscribeResultItem.cs | 8 + .../MqttClientUnsubscribeOptions.cs | 11 ++ .../MqttClientUnsubscribeOptionsBuilder.cs | 27 +++ .../MqttClientUnsubscribeResultItem.cs | 8 + .../MQTTnet/IApplicationMessagePublisher.cs | 6 + Source/MQTTnet/IApplicationMessageReceiver.cs | 4 + Source/MQTTnet/IMqttFactory.cs | 6 + Source/MQTTnet/MqttApplicationMessage.cs | 71 +++++++ .../MQTTnet/MqttApplicationMessageBuilder.cs | 183 +++++++++++++++++- .../MqttApplicationMessageExtensions.cs | 5 + Source/MQTTnet/MqttTopicFilter.cs | 22 ++- Source/MQTTnet/MqttTopicFilterBuilder.cs | 40 ++++ Source/MQTTnet/Server/IMqttServerFactory.cs | 23 +++ 33 files changed, 1176 insertions(+), 20 deletions(-) diff --git a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs index cc2490c..4e06eaf 100644 --- a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs +++ b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs @@ -16,36 +16,95 @@ namespace MQTTnet.Extensions.ManagedClient /// IMqttClient InternalClient { get; } + /// + /// Gets a value indicating whether the client is started or not. + /// bool IsStarted { get; } - + + /// + /// Gets a value indicating whether the client is connected or not. + /// bool IsConnected { get; } + /// + /// Gets a pending application message count. + /// int PendingApplicationMessagesCount { get; } + /// + /// Gets the MQTT client options. + /// IManagedMqttClientOptions Options { get; } + /// + /// Gets or sets the connected handler. + /// IMqttClientConnectedHandler ConnectedHandler { get; set; } - + + /// + /// Gets or sets the disconnected handler. + /// IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } + /// + /// Gets or sets the application message process handler. + /// IApplicationMessageProcessedHandler ApplicationMessageProcessedHandler { get; set; } - + + /// + /// Gets or sets the application message skipped handler. + /// IApplicationMessageSkippedHandler ApplicationMessageSkippedHandler { get; set; } + /// + /// Gets or sets the connecting failed handler. + /// IConnectingFailedHandler ConnectingFailedHandler { get; set; } + /// + /// Gets or sets the synchronizing subscriptions failed handler. + /// ISynchronizingSubscriptionsFailedHandler SynchronizingSubscriptionsFailedHandler { get; set; } + /// + /// Starts the client. + /// + /// The options. + /// A representing any asynchronous operation. Task StartAsync(IManagedMqttClientOptions options); - + + /// + /// Stops the client. + /// + /// A representing any asynchronous operation. Task StopAsync(); - + + /// + /// Pings the server. + /// + /// A token to cancel the task. + /// A representing any asynchronous operation. Task PingAsync(CancellationToken cancellationToken); + /// + /// Subscribes the client. + /// + /// The topic filters. + /// A representing any asynchronous operation. Task SubscribeAsync(IEnumerable topicFilters); - + + /// + /// Unsubscribes the client. + /// + /// The topics. + /// A representing any asynchronous operation. Task UnsubscribeAsync(IEnumerable topics); + /// + /// Publishes a message from the client. + /// + /// The application messages. + /// A representing any asynchronous operation. Task PublishAsync(ManagedMqttApplicationMessage applicationMessages); } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs b/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs index 8b7be27..233ee57 100644 --- a/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs +++ b/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs @@ -4,6 +4,11 @@ namespace MQTTnet.Client.Connecting { public interface IMqttClientConnectedHandler { + /// + /// Handles the events when a client gets connected. + /// + /// The event args. + /// A representing any asynchronous operation. Task HandleConnectedAsync(MqttClientConnectedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs b/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs index 7419fae..dfcaaff 100644 --- a/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs +++ b/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs @@ -7,42 +7,110 @@ namespace MQTTnet.Client.Connecting // TODO: Consider renaming this to _MqttClientConnectResult_ public class MqttClientAuthenticateResult { + /// + /// Gets or sets the result code. + /// Hint: MQTT 5 feature only. + /// public MqttClientConnectResultCode ResultCode { get; set; } + /// + /// Gets or sets a value indicating whether the session is present or not. + /// public bool IsSessionPresent { get; set; } + /// + /// Gets or sets a value indicating whether wildcard subscriptions are available. + /// public bool? WildcardSubscriptionAvailable { get; set; } + /// + /// Gets or sets a value indicating whether retained messages are available. + /// public bool? RetainAvailable { get; set; } + /// + /// Gets or sets the assigned client identifier. + /// public string AssignedClientIdentifier { get; set; } + /// + /// Gets or sets the authentication method. + /// Hint: MQTT 5 feature only. + /// public string AuthenticationMethod { get; set; } + /// + /// Gets or sets the authentication data. + /// Hint: MQTT 5 feature only. + /// public byte[] AuthenticationData { get; set; } + /// + /// Gets or sets the maximum packet size. + /// public uint? MaximumPacketSize { get; set; } + /// + /// Gets or sets the reason string. + /// Hint: MQTT 5 feature only. + /// public string ReasonString { get; set; } + /// + /// Gets or sets the receive maximum. + /// public ushort? ReceiveMaximum { get; set; } + /// + /// Gets or sets the maximum quality od service level. + /// public MqttQualityOfServiceLevel MaximumQoS { get; set; } + /// + /// Gets or sets the response information. + /// Hint: MQTT 5 feature only. + /// public string ResponseInformation { get; set; } + /// + /// Gets or sets the topic alias maximum. + /// public ushort? TopicAliasMaximum { get; set; } + /// + /// Gets or sets the server reference. + /// public string ServerReference { get; set; } + /// + /// Gets or sets the server keep alive. + /// public ushort? ServerKeepAlive { get; set; } + /// + /// Gets or sets the session expiry interval. + /// public uint? SessionExpiryInterval { get; set; } + /// + /// Gets or sets a value indicating whether the subscription identifiers are available or not. + /// Hint: MQTT 5 feature only. + /// public bool? SubscriptionIdentifiersAvailable { get; set; } + /// + /// Gets or sets a value indicating whether the shared subscriptions are available or not. + /// Hint: MQTT 5 feature only. + /// public bool? SharedSubscriptionAvailable { get; set; } + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } } } diff --git a/Source/MQTTnet/Client/Connecting/MqttClientConnectedEventArgs.cs b/Source/MQTTnet/Client/Connecting/MqttClientConnectedEventArgs.cs index e7f97b9..02cd47f 100644 --- a/Source/MQTTnet/Client/Connecting/MqttClientConnectedEventArgs.cs +++ b/Source/MQTTnet/Client/Connecting/MqttClientConnectedEventArgs.cs @@ -9,6 +9,10 @@ namespace MQTTnet.Client.Connecting AuthenticateResult = authenticateResult ?? throw new ArgumentNullException(nameof(authenticateResult)); } + /// + /// Gets the authentication result. + /// Hint: MQTT 5 feature only. + /// public MqttClientAuthenticateResult AuthenticateResult { get; } } } diff --git a/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs b/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs index 14347bf..81e0b9b 100644 --- a/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs +++ b/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs @@ -4,6 +4,11 @@ namespace MQTTnet.Client.Disconnecting { public interface IMqttClientDisconnectedHandler { + /// + /// Handles the events when a client gets disconnected. + /// + /// The event args. + /// A representing any asynchronous operation. Task HandleDisconnectedAsync(MqttClientDisconnectedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptions.cs b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptions.cs index 995806e..97ab644 100644 --- a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptions.cs +++ b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptions.cs @@ -2,8 +2,16 @@ { public class MqttClientDisconnectOptions { + /// + /// Gets or sets the reason code. + /// Hint: MQTT 5 feature only. + /// public MqttClientDisconnectReason ReasonCode { get; set; } = MqttClientDisconnectReason.NormalDisconnection; + /// + /// Gets or sets the reason string. + /// Hint: MQTT 5 feature only. + /// public string ReasonString { get; set; } } } diff --git a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs index 5e2317c..aa02634 100644 --- a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs +++ b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs @@ -15,12 +15,26 @@ namespace MQTTnet.Client.Disconnecting ReasonCode = reason; } + /// + /// Gets a value indicating whether the client was connected or not. + /// public bool ClientWasConnected { get; } + /// + /// Gets the exception. + /// public Exception Exception { get; } + /// + /// Gets the authentication result. + /// Hint: MQTT 5 feature only. + /// public MqttClientAuthenticateResult AuthenticateResult { get; } + /// + /// Gets or sets the reason. + /// Hint: MQTT 5 feature only. + /// public MqttClientDisconnectReason Reason { get; set; } [Obsolete("Please use 'Reason' instead. This property will be removed in the future!")] diff --git a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs index 8cd3542..69a689c 100644 --- a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs +++ b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs @@ -4,6 +4,11 @@ namespace MQTTnet.Client.ExtendedAuthenticationExchange { public interface IMqttExtendedAuthenticationExchangeHandler { + /// + /// Handles the authentication request. + /// + /// The context. + /// A representing any asynchronous operation. Task HandleRequestAsync(MqttExtendedAuthenticationExchangeContext context); } } diff --git a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs index 9e88f03..a83576d 100644 --- a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs +++ b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs @@ -20,16 +20,42 @@ namespace MQTTnet.Client.ExtendedAuthenticationExchange Client = client ?? throw new ArgumentNullException(nameof(client)); } + /// + /// Gets the reason code. + /// Hint: MQTT 5 feature only. + /// public MqttAuthenticateReasonCode ReasonCode { get; } + /// + /// Gets the reason string. + /// Hint: MQTT 5 feature only. + /// public string ReasonString { get; } + /// + /// Gets the authentication method. + /// Hint: MQTT 5 feature only. + /// public string AuthenticationMethod { get; } + /// + /// Gets the authentication data. + /// Hint: MQTT 5 feature only. + /// public byte[] AuthenticationData { get; } + /// + /// Gets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; } + /// + /// Gets the client. + /// public IMqttClient Client { get; } } } diff --git a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeData.cs b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeData.cs index 8a49b08..29f3821 100644 --- a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeData.cs +++ b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeData.cs @@ -6,12 +6,33 @@ namespace MQTTnet.Client.ExtendedAuthenticationExchange { public class MqttExtendedAuthenticationExchangeData { + /// + /// Gets or sets the reason code. + /// Hint: MQTT 5 feature only. + /// public MqttAuthenticateReasonCode ReasonCode { get; set; } + /// + /// Gets or sets the reason string. + /// Hint: MQTT 5 feature only. + /// public string ReasonString { get; set; } + /// + /// Gets or sets the authentication data. + /// Authentication data is binary information used to transmit multiple iterations of cryptographic secrets of protocol steps. + /// The content of the authentication data is highly dependent on the specific implementation of the authentication method. + /// Hint: MQTT 5 feature only. + /// public byte[] AuthenticationData { get; set; } + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; } } } diff --git a/Source/MQTTnet/Client/IMqttClient.cs b/Source/MQTTnet/Client/IMqttClient.cs index 58cfa0c..95ee1d9 100644 --- a/Source/MQTTnet/Client/IMqttClient.cs +++ b/Source/MQTTnet/Client/IMqttClient.cs @@ -12,19 +12,75 @@ namespace MQTTnet.Client { public interface IMqttClient : IApplicationMessageReceiver, IApplicationMessagePublisher, IDisposable { + /// + /// Gets a value indicating whether the client is connected or not. + /// bool IsConnected { get; } + + /// + /// Gets the options. + /// This contains all the set options for the client. + /// IMqttClientOptions Options { get; } + /// + /// Gets or sets the connected handler that is fired after the client has connected to the server successfully. + /// Hint: Initialize handlers before you connect the client to avoid issues. + /// IMqttClientConnectedHandler ConnectedHandler { get; set; } + /// + /// Gets or sets the disconnected handler that is fired after the client has disconnected from the server. + /// Hint: Initialize handlers before you connect the client to avoid issues. + /// IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } + /// + /// Connects the client to the server using the specified options. + /// + /// The options that can be used on connect. + /// A cancellation token to stop the task. + /// A result containing the authentication result information. Task ConnectAsync(IMqttClientOptions options, CancellationToken cancellationToken); + + /// + /// Disconnects the client from the server. + /// + /// The options containing a disconnect reason. + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task DisconnectAsync(MqttClientDisconnectOptions options, CancellationToken cancellationToken); + + /// + /// Pings the server. + /// + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task PingAsync(CancellationToken cancellationToken); + /// + /// Sends extended authentication data. + /// Hint: MQTT 5 feature only. + /// + /// The extended data. + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task SendExtendedAuthenticationExchangeDataAsync(MqttExtendedAuthenticationExchangeData data, CancellationToken cancellationToken); + + /// + /// Subscribes the client to topics. + /// + /// The subscription options. + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task SubscribeAsync(MqttClientSubscribeOptions options, CancellationToken cancellationToken); + + /// + /// Unsubscribes the client from topics. + /// + /// The unsubscription options. + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task UnsubscribeAsync(MqttClientUnsubscribeOptions options, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/IMqttClientFactory.cs b/Source/MQTTnet/Client/IMqttClientFactory.cs index b256e74..54707ff 100644 --- a/Source/MQTTnet/Client/IMqttClientFactory.cs +++ b/Source/MQTTnet/Client/IMqttClientFactory.cs @@ -1,5 +1,4 @@ -using System; -using MQTTnet.Adapter; +using MQTTnet.Adapter; using MQTTnet.Diagnostics; using MQTTnet.LowLevelClient; @@ -7,22 +6,67 @@ namespace MQTTnet.Client { public interface IMqttClientFactory { + /// + /// A method to tell the client to use the adapter factory. + /// + /// The client adapter factory. + /// A new . IMqttFactory UseClientAdapterFactory(IMqttClientAdapterFactory clientAdapterFactory); + /// + /// Creates a new low level MQTT client. + /// + /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(); + /// + /// Creates a new low level MQTT client. + /// + /// The logger. + /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttNetLogger logger); + /// + /// Creates a new low level MQTT client. + /// + /// The client adapter factory. + /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttClientAdapterFactory clientAdapterFactory); + /// + /// Creates a new low level MQTT client. + /// + /// The logger. + /// The client adapter factory. + /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttNetLogger logger, IMqttClientAdapterFactory clientAdapterFactory); + /// + /// Creates a new MQTT client. + /// + /// A new . IMqttClient CreateMqttClient(); + /// + /// Creates a new MQTT client. + /// + /// The logger. + /// A new . IMqttClient CreateMqttClient(IMqttNetLogger logger); + /// + /// Creates a new MQTT client. + /// + /// The adapter factory. + /// A new . IMqttClient CreateMqttClient(IMqttClientAdapterFactory adapterFactory); + /// + /// Creates a new MQTT client. + /// + /// The logger. + /// The adapter factory. + /// A new . IMqttClient CreateMqttClient(IMqttNetLogger logger, IMqttClientAdapterFactory adapterFactory); } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/Options/IMqttClientOptions.cs b/Source/MQTTnet/Client/Options/IMqttClientOptions.cs index e46162a..642a872 100644 --- a/Source/MQTTnet/Client/Options/IMqttClientOptions.cs +++ b/Source/MQTTnet/Client/Options/IMqttClientOptions.cs @@ -8,26 +8,122 @@ namespace MQTTnet.Client.Options { public interface IMqttClientOptions { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; } + + /// + /// Gets a value indicating whether clean sessions are used or not. + /// When a client connects to a broker it can connect using either a non persistent connection (clean session) or a persistent connection. + /// With a non persistent connection the broker doesn't store any subscription information or undelivered messages for the client. + /// This mode is ideal when the client only publishes messages. + /// It can also connect as a durable client using a persistent connection. + /// In this mode, the broker will store subscription information, and undelivered messages for the client. + /// bool CleanSession { get; } + + /// + /// Gets the credentials. + /// IMqttClientCredentials Credentials { get; } + + /// + /// Gets the extended authentication exchange handler. + /// IMqttExtendedAuthenticationExchangeHandler ExtendedAuthenticationExchangeHandler { get; } + + /// + /// Gets the protocol version. + /// MqttProtocolVersion ProtocolVersion { get; } + + /// + /// Gets the channel options. + /// IMqttClientChannelOptions ChannelOptions { get; } + /// + /// Gets the timeout the communication uses. + /// TimeSpan CommunicationTimeout { get; } + + /// + /// Gets the keep alive period. + /// The connection is normally left open by the client so that is can send and receive data at any time. + /// If no data flows over an open connection for a certain time period then the client will generate a PINGREQ and expect to receive a PINGRESP from the broker. + /// This message exchange confirms that the connection is open and working. + /// This period is known as the keep alive period. + /// TimeSpan KeepAlivePeriod { get; } + + /// + /// Gets the last will message. + /// In MQTT, you use the last will message feature to notify other clients about an ungracefully disconnected client. + /// MqttApplicationMessage WillMessage { get; } + + /// + /// Gets the will delay interval. + /// This is the time between the client disconnect and the time the will message will be sent. + /// uint? WillDelayInterval { get; } + /// + /// Gets the authentication method. + /// Hint: MQTT 5 feature only. + /// string AuthenticationMethod { get; } + + /// + /// Gets the authentication data. + /// Hint: MQTT 5 feature only. + /// byte[] AuthenticationData { get; } + + /// + /// Gets the maximum packet size. + /// uint? MaximumPacketSize { get; } + + /// + /// Gets the receive maximum. + /// This gives the maximum length of the receive messages. + /// ushort? ReceiveMaximum { get; } + + /// + /// Gets the request problem information. + /// Hint: MQTT 5 feature only. + /// bool? RequestProblemInformation { get; } + + /// + /// Gets the request response information. + /// Hint: MQTT 5 feature only. + /// bool? RequestResponseInformation { get; } + + /// + /// Gets the session expiry interval. + /// The time after a session expires when it's not actively used. + /// uint? SessionExpiryInterval { get; } + + /// + /// Gets the topic alias maximum. + /// This gives the maximum length of the topic alias. + /// ushort? TopicAliasMaximum { get; } + + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// List UserProperties { get; set; } } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs b/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs index 3827f05..0a86301 100644 --- a/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs +++ b/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs @@ -5,12 +5,24 @@ namespace MQTTnet.Client.Options { public class MqttClientCertificateValidationCallbackContext { + /// + /// Gets or sets the certificate. + /// public X509Certificate Certificate { get; set; } + /// + /// Gets or sets the certificate chain. + /// public X509Chain Chain { get; set; } + /// + /// Gets or sets the SSL policy errors. + /// public SslPolicyErrors SslPolicyErrors { get; set; } + /// + /// Gets or sets the client options. + /// public IMqttClientChannelOptions ClientOptions { get; set; } } } diff --git a/Source/MQTTnet/Client/Options/MqttClientOptions.cs b/Source/MQTTnet/Client/Options/MqttClientOptions.cs index 79c6c70..e150e49 100644 --- a/Source/MQTTnet/Client/Options/MqttClientOptions.cs +++ b/Source/MQTTnet/Client/Options/MqttClientOptions.cs @@ -8,28 +8,122 @@ namespace MQTTnet.Client.Options { public class MqttClientOptions : IMqttClientOptions { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; set; } = Guid.NewGuid().ToString("N"); + + /// + /// Gets or sets a value indicating whether clean sessions are used or not. + /// When a client connects to a broker it can connect using either a non persistent connection (clean session) or a persistent connection. + /// With a non persistent connection the broker doesn't store any subscription information or undelivered messages for the client. + /// This mode is ideal when the client only publishes messages. + /// It can also connect as a durable client using a persistent connection. + /// In this mode, the broker will store subscription information, and undelivered messages for the client. + /// public bool CleanSession { get; set; } = true; + + /// + /// Gets or sets the credentials. + /// public IMqttClientCredentials Credentials { get; set; } + + /// + /// Gets or sets the extended authentication exchange handler. + /// public IMqttExtendedAuthenticationExchangeHandler ExtendedAuthenticationExchangeHandler { get; set; } + + /// + /// Gets or sets the protocol version. + /// public MqttProtocolVersion ProtocolVersion { get; set; } = MqttProtocolVersion.V311; + /// + /// Gets or sets the channel options. + /// public IMqttClientChannelOptions ChannelOptions { get; set; } + + /// + /// Gets or sets the timeout the communication uses. + /// public TimeSpan CommunicationTimeout { get; set; } = TimeSpan.FromSeconds(10); + + /// + /// Gets or sets the keep alive period. + /// The connection is normally left open by the client so that is can send and receive data at any time. + /// If no data flows over an open connection for a certain time period then the client will generate a PINGREQ and expect to receive a PINGRESP from the broker. + /// This message exchange confirms that the connection is open and working. + /// This period is known as the keep alive period. + /// public TimeSpan KeepAlivePeriod { get; set; } = TimeSpan.FromSeconds(15); + /// + /// Gets or sets the last will message. + /// In MQTT, you use the last will message feature to notify other clients about an ungracefully disconnected client. + /// public MqttApplicationMessage WillMessage { get; set; } + + /// + /// Gets or sets the will delay interval. + /// This is the time between the client disconnect and the time the will message will be sent. + /// public uint? WillDelayInterval { get; set; } + /// + /// Gets or sets the authentication method. + /// Hint: MQTT 5 feature only. + /// public string AuthenticationMethod { get; set; } + + /// + /// Gets or sets the authentication data. + /// Hint: MQTT 5 feature only. + /// public byte[] AuthenticationData { get; set; } + /// + /// Gets or sets the maximum packet size. + /// public uint? MaximumPacketSize { get; set; } + + /// + /// Gets or sets the receive maximum. + /// This gives the maximum length of the receive messages. + /// public ushort? ReceiveMaximum { get; set; } + + /// + /// Gets or sets the request problem information. + /// Hint: MQTT 5 feature only. + /// public bool? RequestProblemInformation { get; set; } + + /// + /// Gets or sets the request response information. + /// Hint: MQTT 5 feature only. + /// public bool? RequestResponseInformation { get; set; } + + /// + /// Gets or sets the session expiry interval. + /// The time after a session expires when it's not actively used. + /// public uint? SessionExpiryInterval { get; set; } + + /// + /// Gets or sets the topic alias maximum. + /// This gives the maximum length of the topic alias. + /// public ushort? TopicAliasMaximum { get; set; } + + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } } } diff --git a/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs b/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs index 68d1aa3..402f28a 100644 --- a/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs @@ -17,6 +17,11 @@ namespace MQTTnet.Client.Options MqttClientOptionsBuilderTlsParameters _tlsParameters; MqttClientWebSocketProxyOptions _proxyOptions; + /// + /// Adds the protocol version to the MQTT client options. + /// + /// The protocol version. + /// A new instance of the class. public MqttClientOptionsBuilder WithProtocolVersion(MqttProtocolVersion value) { if (value == MqttProtocolVersion.Unknown) @@ -28,47 +33,88 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds the communication timeout to the MQTT client options. + /// + /// The timeout. + /// A new instance of the class. public MqttClientOptionsBuilder WithCommunicationTimeout(TimeSpan value) { _options.CommunicationTimeout = value; return this; } + /// + /// Adds the clean session flag to the MQTT client options. + /// + /// The clean session flag. + /// A new instance of the class. public MqttClientOptionsBuilder WithCleanSession(bool value = true) { _options.CleanSession = value; return this; } + /// + /// Adds the keep alive send interval to the MQTT client options. + /// + /// The keep alive interval. + /// A new instance of the class. [Obsolete("This method is no longer supported. The client will send ping requests just before the keep alive interval is going to elapse. As per MQTT RFC the serve has to wait 1.5 times the interval so we don't need this anymore.")] public MqttClientOptionsBuilder WithKeepAliveSendInterval(TimeSpan value) { return this; } + /// + /// Adds no keep alive period to the MQTT client options. + /// + /// A new instance of the class. public MqttClientOptionsBuilder WithNoKeepAlive() { return WithKeepAlivePeriod(TimeSpan.Zero); } + /// + /// Adds the keep alive period to the MQTT client options. + /// + /// The keep alive period. + /// A new instance of the class. public MqttClientOptionsBuilder WithKeepAlivePeriod(TimeSpan value) { _options.KeepAlivePeriod = value; return this; } + /// + /// Adds the client identifier to the MQTT client options. + /// + /// The client identifier. + /// A new instance of the class. public MqttClientOptionsBuilder WithClientId(string value) { _options.ClientId = value; return this; } + /// + /// Adds the will message to the MQTT client options. + /// + /// The will message. + /// A new instance of the class. public MqttClientOptionsBuilder WithWillMessage(MqttApplicationMessage value) { _options.WillMessage = value; return this; } + /// + /// Adds the authentication to the MQTT client options. + /// Hint: MQTT 5 feature only. + /// + /// The authentication method. + /// The data. + /// A new instance of the class. public MqttClientOptionsBuilder WithAuthentication(string method, byte[] data) { _options.AuthenticationMethod = method; @@ -76,48 +122,92 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds the will delay interval to the MQTT client options. + /// + /// The will delay interval. + /// A new instance of the class. public MqttClientOptionsBuilder WithWillDelayInterval(uint? willDelayInterval) { _options.WillDelayInterval = willDelayInterval; return this; } + /// + /// Adds the topic alias maximum to the MQTT client options. + /// + /// The topic alias maximum. + /// A new instance of the class. public MqttClientOptionsBuilder WithTopicAliasMaximum(ushort? topicAliasMaximum) { _options.TopicAliasMaximum = topicAliasMaximum; return this; } + /// + /// Adds the maximum packet size to the MQTT client options. + /// + /// The maximum packet size. + /// A new instance of the class. public MqttClientOptionsBuilder WithMaximumPacketSize(uint? maximumPacketSize) { _options.MaximumPacketSize = maximumPacketSize; return this; } + /// + /// Adds the receive maximum to the MQTT client options. + /// + /// The receive maximum. + /// A new instance of the class. public MqttClientOptionsBuilder WithReceiveMaximum(ushort? receiveMaximum) { _options.ReceiveMaximum = receiveMaximum; return this; } + /// + /// Adds the request problem information to the MQTT client options. + /// Hint: MQTT 5 feature only. + /// + /// The request problem information. + /// A new instance of the class. public MqttClientOptionsBuilder WithRequestProblemInformation(bool? requestProblemInformation = true) { _options.RequestProblemInformation = requestProblemInformation; return this; } + /// + /// Adds the request response information to the MQTT client options. + /// Hint: MQTT 5 feature only. + /// + /// The request response information. + /// A new instance of the class. public MqttClientOptionsBuilder WithRequestResponseInformation(bool? requestResponseInformation = true) { _options.RequestResponseInformation = requestResponseInformation; return this; } + /// + /// Adds the session expiry interval to the MQTT client options. + /// + /// The session expiry interval. + /// A new instance of the class. public MqttClientOptionsBuilder WithSessionExpiryInterval(uint? sessionExpiryInterval) { _options.SessionExpiryInterval = sessionExpiryInterval; return this; } + /// + /// Adds the user property to the MQTT client options. + /// Hint: MQTT 5 feature only. + /// + /// The user property name. + /// The user property value. + /// A new instance of the class. public MqttClientOptionsBuilder WithUserProperty(string name, string value) { if (name is null) throw new ArgumentNullException(nameof(name)); @@ -132,6 +222,12 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds the credentials to the MQTT client options. + /// + /// The user name. + /// The password. + /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(string username, string password = null) { byte[] passwordBuffer = null; @@ -144,6 +240,12 @@ namespace MQTTnet.Client.Options return WithCredentials(username, passwordBuffer); } + /// + /// Adds the credentials to the MQTT client options. + /// + /// The user name. + /// The password. + /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(string username, byte[] password = null) { _options.Credentials = new MqttClientCredentials @@ -155,6 +257,11 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds the credentials to the MQTT client options. + /// + /// The credentials. + /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(IMqttClientCredentials credentials) { _options.Credentials = credentials; @@ -162,12 +269,23 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a extended authentication exchange handler to the MQTT client options. + /// + /// The handler. + /// A new instance of the class. public MqttClientOptionsBuilder WithExtendedAuthenticationExchangeHandler(IMqttExtendedAuthenticationExchangeHandler handler) { _options.ExtendedAuthenticationExchangeHandler = handler; return this; } + /// + /// Adds a TCP server connection to the MQTT client options. + /// + /// The server. + /// The port. + /// A new instance of the class. public MqttClientOptionsBuilder WithTcpServer(string server, int? port = null) { _tcpOptions = new MqttClientTcpOptions @@ -179,6 +297,11 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a TCP server connection to the MQTT client options. + /// + /// The options builder. + /// A new instance of the class. // TODO: Consider creating _MqttClientTcpOptionsBuilder_ as overload. public MqttClientOptionsBuilder WithTcpServer(Action optionsBuilder) { @@ -190,6 +313,16 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a proxy connection to the MQTT client options. + /// + /// The address. + /// The user name. + /// The password. + /// The domain. + /// The bypass on local flag. + /// The bypass list. + /// A new instance of the class. public MqttClientOptionsBuilder WithProxy(string address, string username = null, string password = null, string domain = null, bool bypassOnLocal = false, string[] bypassList = null) { _proxyOptions = new MqttClientWebSocketProxyOptions @@ -205,6 +338,11 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a proxy connection to the MQTT client options. + /// + /// The options builder. + /// A new instance of the class. public MqttClientOptionsBuilder WithProxy(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -214,6 +352,12 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a web socket server to the MQTT client options. + /// + /// The uri. + /// The parameters. + /// A new instance of the class. public MqttClientOptionsBuilder WithWebSocketServer(string uri, MqttClientOptionsBuilderWebSocketParameters parameters = null) { _webSocketOptions = new MqttClientWebSocketOptions @@ -226,6 +370,11 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds a web socket server to the MQTT client options. + /// + /// The options builder. + /// A new instance of the class. public MqttClientOptionsBuilder WithWebSocketServer(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -236,17 +385,31 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Adds TLS to the MQTT client options. + /// + /// The parameters. + /// A new instance of the class. public MqttClientOptionsBuilder WithTls(MqttClientOptionsBuilderTlsParameters parameters) { _tlsParameters = parameters; return this; } + /// + /// Adds TLS to the MQTT client options. + /// + /// A new instance of the class. public MqttClientOptionsBuilder WithTls() { return WithTls(new MqttClientOptionsBuilderTlsParameters { UseTls = true }); } + /// + /// Adds TLS to the MQTT client options. + /// + /// The options builder. + /// A new instance of the class. public MqttClientOptionsBuilder WithTls(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -256,6 +419,10 @@ namespace MQTTnet.Client.Options return this; } + /// + /// Builds the MQTT client options. + /// + /// The . public IMqttClientOptions Build() { if (_tcpOptions == null && _webSocketOptions == null) diff --git a/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs b/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs index 15035ec..0a51c98 100644 --- a/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs +++ b/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs @@ -6,12 +6,30 @@ namespace MQTTnet.Client.Publishing { public class MqttClientPublishResult { + /// + /// Gets or sets the packet identifier. + /// public ushort? PacketIdentifier { get; set; } + /// + /// Gets or sets the reason code. + /// Hint: MQTT 5 feature only. + /// public MqttClientPublishReasonCode ReasonCode { get; set; } = MqttClientPublishReasonCode.Success; + /// + /// Gets or sets the reason string. + /// Hint: MQTT 5 feature only. + /// public string ReasonString { get; set; } + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } } } diff --git a/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs b/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs index 3ea7317..199adba 100644 --- a/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs +++ b/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs @@ -4,6 +4,11 @@ namespace MQTTnet.Client.Receiving { public interface IMqttApplicationMessageReceivedHandler { + /// + /// Handles the application message received event. + /// + /// The event args. + /// A representing any asynchronous operation. Task HandleApplicationMessageReceivedAsync(MqttApplicationMessageReceivedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptions.cs b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptions.cs index 42c38e1..2c43c42 100644 --- a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptions.cs +++ b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptions.cs @@ -5,10 +5,28 @@ namespace MQTTnet.Client.Subscribing { public class MqttClientSubscribeOptions { + /// + /// Gets or sets a list of topic filters the client wants to subscribe to. + /// Topic filters can include regular topics or wild cards. + /// public List TopicFilters { get; set; } = new List(); + /// + /// Gets or sets the subscription identifier. + /// The client can specify a subscription identifier when subscribing. + /// The broker will establish and store the mapping relationship between this subscription and subscription identifier when successfully create or modify subscription. + /// The broker will return the subscription identifier associated with this PUBLISH packet and the PUBLISH packet to the client when need to forward PUBLISH packets matching this subscription to this client. + /// Hint: MQTT 5 feature only. + /// public uint? SubscriptionIdentifier { get; set; } + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } } } diff --git a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs index 97b5b77..96e6c5d 100644 --- a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs @@ -9,6 +9,13 @@ namespace MQTTnet.Client.Subscribing { private readonly MqttClientSubscribeOptions _subscribeOptions = new MqttClientSubscribeOptions(); + /// + /// Adds the user property to the subscribe options. + /// Hint: MQTT 5 feature only. + /// + /// The property name. + /// The property value. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithUserProperty(string name, string value) { if (name == null) throw new ArgumentNullException(nameof(name)); @@ -24,13 +31,26 @@ namespace MQTTnet.Client.Subscribing return this; } + /// + /// Adds the subscription identifier to the subscribe options. + /// + /// The subscription identifier. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithSubscriptionIdentifier(uint? subscriptionIdentifier) { _subscribeOptions.SubscriptionIdentifier = subscriptionIdentifier; - return this; } + /// + /// Adds a topic filter to the subscribe options. + /// + /// The topic. + /// The quality of service level. + /// A value indicating whether to not send messages originating on this client (noLocal) or not. + /// A value indicating whether messages are retained as published or not. + /// The retain handling. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter( string topic, MqttQualityOfServiceLevel qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce, @@ -48,6 +68,11 @@ namespace MQTTnet.Client.Subscribing }); } + /// + /// Adds the topic filter to the subscribe options. + /// + /// The topic filter builder. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(Action topicFilterBuilder) { if (topicFilterBuilder == null) throw new ArgumentNullException(nameof(topicFilterBuilder)); @@ -58,6 +83,11 @@ namespace MQTTnet.Client.Subscribing return WithTopicFilter(internalTopicFilterBuilder); } + /// + /// Adds the topic filter to the subscribe options. + /// + /// The topic filter builder. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(MqttTopicFilterBuilder topicFilterBuilder) { if (topicFilterBuilder == null) throw new ArgumentNullException(nameof(topicFilterBuilder)); @@ -65,6 +95,11 @@ namespace MQTTnet.Client.Subscribing return WithTopicFilter(topicFilterBuilder.Build()); } + /// + /// Adds the topic filter to the subscribe options. + /// + /// The topic filter. + /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(MqttTopicFilter topicFilter) { if (topicFilter == null) throw new ArgumentNullException(nameof(topicFilter)); @@ -79,6 +114,10 @@ namespace MQTTnet.Client.Subscribing return this; } + /// + /// Builds the subscription options. + /// + /// A new instance of the class. public MqttClientSubscribeOptions Build() { return _subscribeOptions; diff --git a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeResultItem.cs b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeResultItem.cs index 65f15c4..3e2d27f 100644 --- a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeResultItem.cs +++ b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeResultItem.cs @@ -10,8 +10,16 @@ namespace MQTTnet.Client.Subscribing ResultCode = resultCode; } + /// + /// Gets or sets the topic filter. + /// The topic filter can contain topics and wildcards. + /// public MqttTopicFilter TopicFilter { get; } + /// + /// Gets or sets the result code. + /// Hint: MQTT 5 feature only. + /// public MqttClientSubscribeResultCode ResultCode { get; } } } diff --git a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptions.cs b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptions.cs index 73c21ef..09a4ce2 100644 --- a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptions.cs +++ b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptions.cs @@ -5,8 +5,19 @@ namespace MQTTnet.Client.Unsubscribing { public class MqttClientUnsubscribeOptions { + /// + /// Gets or sets a list of topic filters the client wants to unsubscribe from. + /// Topic filters can include regular topics or wild cards. + /// public List TopicFilters { get; set; } = new List(); + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } = new List(); } } diff --git a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs index 8516243..56a1997 100644 --- a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs @@ -8,6 +8,13 @@ namespace MQTTnet.Client.Unsubscribing { private readonly MqttClientUnsubscribeOptions _unsubscribeOptions = new MqttClientUnsubscribeOptions(); + /// + /// Adds the user property to the unsubscribe options. + /// Hint: MQTT 5 feature only. + /// + /// The property name. + /// The property value. + /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithUserProperty(string name, string value) { if (name is null) throw new ArgumentNullException(nameof(name)); @@ -16,6 +23,12 @@ namespace MQTTnet.Client.Unsubscribing return WithUserProperty(new MqttUserProperty(name, value)); } + /// + /// Adds the user property to the unsubscribe options. + /// Hint: MQTT 5 feature only. + /// + /// The user property. + /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithUserProperty(MqttUserProperty userProperty) { if (userProperty is null) throw new ArgumentNullException(nameof(userProperty)); @@ -30,6 +43,11 @@ namespace MQTTnet.Client.Unsubscribing return this; } + /// + /// Adds the topic filter to the unsubscribe options. + /// + /// The topic. + /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithTopicFilter(string topic) { if (topic is null) throw new ArgumentNullException(nameof(topic)); @@ -44,6 +62,11 @@ namespace MQTTnet.Client.Unsubscribing return this; } + /// + /// Adds the topic filter to the unsubscribe options. + /// + /// The topic filter. + /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithTopicFilter(MqttTopicFilter topicFilter) { if (topicFilter is null) throw new ArgumentNullException(nameof(topicFilter)); @@ -51,6 +74,10 @@ namespace MQTTnet.Client.Unsubscribing return WithTopicFilter(topicFilter.Topic); } + /// + /// Builds the unsubscription options. + /// + /// A new instance of the class. public MqttClientUnsubscribeOptions Build() { return _unsubscribeOptions; diff --git a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeResultItem.cs b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeResultItem.cs index 755ee43..065fb7f 100644 --- a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeResultItem.cs +++ b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeResultItem.cs @@ -10,8 +10,16 @@ namespace MQTTnet.Client.Unsubscribing ReasonCode = reasonCode; } + /// + /// Gets or sets the topic filter. + /// The topic filter can contain topics and wildcards. + /// public string TopicFilter { get; } + /// + /// Gets or sets the result code. + /// Hint: MQTT 5 feature only. + /// public MqttClientUnsubscribeResultCode ReasonCode { get; } } } \ No newline at end of file diff --git a/Source/MQTTnet/IApplicationMessagePublisher.cs b/Source/MQTTnet/IApplicationMessagePublisher.cs index bf17718..aa3caae 100644 --- a/Source/MQTTnet/IApplicationMessagePublisher.cs +++ b/Source/MQTTnet/IApplicationMessagePublisher.cs @@ -6,6 +6,12 @@ namespace MQTTnet { public interface IApplicationMessagePublisher { + /// + /// Publishes a new application message to the server. + /// + /// The application message. + /// A cancellation token to stop the task. + /// A representing any asynchronous operation. Task PublishAsync(MqttApplicationMessage applicationMessage, CancellationToken cancellationToken); } } diff --git a/Source/MQTTnet/IApplicationMessageReceiver.cs b/Source/MQTTnet/IApplicationMessageReceiver.cs index 4e47485..a44470d 100644 --- a/Source/MQTTnet/IApplicationMessageReceiver.cs +++ b/Source/MQTTnet/IApplicationMessageReceiver.cs @@ -4,6 +4,10 @@ namespace MQTTnet { public interface IApplicationMessageReceiver { + /// + /// Gets or sets the application message received handler that is fired every time a new message is received on the client's subscriptions. + /// Hint: Initialize handlers before you connect the client to avoid issues. + /// IMqttApplicationMessageReceivedHandler ApplicationMessageReceivedHandler { get; set; } } } diff --git a/Source/MQTTnet/IMqttFactory.cs b/Source/MQTTnet/IMqttFactory.cs index 8c0e5af..b68e27a 100644 --- a/Source/MQTTnet/IMqttFactory.cs +++ b/Source/MQTTnet/IMqttFactory.cs @@ -7,8 +7,14 @@ namespace MQTTnet { public interface IMqttFactory : IMqttClientFactory, IMqttServerFactory { + /// + /// Gets the default logger. + /// IMqttNetLogger DefaultLogger { get; } + /// + /// Gets the properties. + /// IDictionary Properties { get; } } } diff --git a/Source/MQTTnet/MqttApplicationMessage.cs b/Source/MQTTnet/MqttApplicationMessage.cs index 6522d42..99068fe 100644 --- a/Source/MQTTnet/MqttApplicationMessage.cs +++ b/Source/MQTTnet/MqttApplicationMessage.cs @@ -6,28 +6,99 @@ namespace MQTTnet { public class MqttApplicationMessage { + /// + /// Gets or sets the MQTT topic. + /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. + /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). + /// public string Topic { get; set; } + /// + /// Gets or sets the payload. + /// The payload is the data bytes sent via the MQTT protocol. + /// public byte[] Payload { get; set; } + /// + /// Gets or sets the quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel QualityOfServiceLevel { get; set; } + /// + /// Gets or sets a value indicating whether the message should be retained or not. + /// A retained message is a normal MQTT message with the retained flag set to true. + /// The broker stores the last retained message and the corresponding QoS for that topic. + /// public bool Retain { get; set; } + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties { get; set; } + /// + /// Gets or sets the content type. + /// The content type must be a UTF-8 encoded string. The content type value identifies the kind of UTF-8 encoded payload. + /// public string ContentType { get; set; } + /// + /// Gets or sets the response topic. + /// In MQTT 5 the ability to publish a response topic was added in the publish message which allows you to implement the request/response pattern between clients that is common in web applications. + /// Hint: MQTT 5 feature only. + /// public string ResponseTopic { get; set; } + /// + /// Gets or sets the payload format indicator. + /// The payload format indicator is part of any MQTT packet that can contain a payload. The indicator is an optional byte value. + /// A value of 0 indicates an “unspecified byte stream”. + /// A value of 1 indicates a "UTF-8 encoded payload". + /// If no payload format indicator is provided, the default value is 0. + /// Hint: MQTT 5 feature only. + /// public MqttPayloadFormatIndicator? PayloadFormatIndicator { get; set; } + /// + /// Gets or sets the message expiry interval. + /// A client can set the message expiry interval in seconds for each PUBLISH message individually. + /// This interval defines the period of time that the broker stores the PUBLISH message for any matching subscribers that are not currently connected. + /// When no message expiry interval is set, the broker must store the message for matching subscribers indefinitely. + /// When the retained=true option is set on the PUBLISH message, this interval also defines how long a message is retained on a topic. + /// Hint: MQTT 5 feature only. + /// public uint? MessageExpiryInterval { get; set; } + /// + /// Gets or sets the topic alias. + /// Topic aliases were introduced are a mechanism for reducing the size of published packets by reducing the size of the topic field. + /// Hint: MQTT 5 feature only. + /// public ushort? TopicAlias { get; set; } + /// + /// Gets or sets the correlation data. + /// In order for the sender to know what sent message the response refers to it can also send correlation data with the published message. + /// Hint: MQTT 5 feature only. + /// public byte[] CorrelationData { get; set; } + /// + /// Gets or sets the subscription identifiers. + /// The client can specify a subscription identifier when subscribing. + /// The broker will establish and store the mapping relationship between this subscription and subscription identifier when successfully create or modify subscription. + /// The broker will return the subscription identifier associated with this PUBLISH packet and the PUBLISH packet to the client when need to forward PUBLISH packets matching this subscription to this client. + /// Hint: MQTT 5 feature only. + /// public List SubscriptionIdentifiers { get; set; } } } diff --git a/Source/MQTTnet/MqttApplicationMessageBuilder.cs b/Source/MQTTnet/MqttApplicationMessageBuilder.cs index 7e48531..e03d259 100644 --- a/Source/MQTTnet/MqttApplicationMessageBuilder.cs +++ b/Source/MQTTnet/MqttApplicationMessageBuilder.cs @@ -11,31 +11,128 @@ namespace MQTTnet { public class MqttApplicationMessageBuilder { + /// + /// The quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// private MqttQualityOfServiceLevel _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; + + /// + /// The MQTT topic. + /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. + /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). + /// private string _topic; + + /// + /// The payload. + /// The payload is the data bytes sent via the MQTT protocol. + /// private byte[] _payload; + + /// + /// A value indicating whether the message should be retained or not. + /// A retained message is a normal MQTT message with the retained flag set to true. + /// The broker stores the last retained message and the corresponding QoS for that topic. + /// private bool _retain; + + /// + /// The content type. + /// The content type must be a UTF-8 encoded string. The content type value identifies the kind of UTF-8 encoded payload. + /// private string _contentType; + + /// + /// The response topic. + /// In MQTT 5 the ability to publish a response topic was added in the publish message which allows you to implement the request/response pattern between clients that is common in web applications. + /// Hint: MQTT 5 feature only. + /// private string _responseTopic; + + /// + /// The correlation data. + /// In order for the sender to know what sent message the response refers to it can also send correlation data with the published message. + /// Hint: MQTT 5 feature only. + /// private byte[] _correlationData; + + /// + /// The topic alias. + /// Topic aliases were introduced are a mechanism for reducing the size of published packets by reducing the size of the topic field. + /// Hint: MQTT 5 feature only. + /// private ushort? _topicAlias; + + /// + /// The subscription identifiers. + /// The client can specify a subscription identifier when subscribing. + /// The broker will establish and store the mapping relationship between this subscription and subscription identifier when successfully create or modify subscription. + /// The broker will return the subscription identifier associated with this PUBLISH packet and the PUBLISH packet to the client when need to forward PUBLISH packets matching this subscription to this client. + /// Hint: MQTT 5 feature only. + /// private List _subscriptionIdentifiers; + + /// + /// The message expiry interval. + /// A client can set the message expiry interval in seconds for each PUBLISH message individually. + /// This interval defines the period of time that the broker stores the PUBLISH message for any matching subscribers that are not currently connected. + /// When no message expiry interval is set, the broker must store the message for matching subscribers indefinitely. + /// When the retained=true option is set on the PUBLISH message, this interval also defines how long a message is retained on a topic. + /// Hint: MQTT 5 feature only. + /// private uint? _messageExpiryInterval; + + /// + /// The payload format indicator. + /// The payload format indicator is part of any MQTT packet that can contain a payload. The indicator is an optional byte value. + /// A value of 0 indicates an “unspecified byte stream”. + /// A value of 1 indicates a "UTF-8 encoded payload". + /// If no payload format indicator is provided, the default value is 0. + /// Hint: MQTT 5 feature only. + /// private MqttPayloadFormatIndicator? _payloadFormatIndicator; + + /// + /// The user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// + /// Hint: MQTT 5 feature only. private List _userProperties; + /// + /// Adds a topic to the message. + /// + /// The topic. + /// A new instance of the class. public MqttApplicationMessageBuilder WithTopic(string topic) { _topic = topic; return this; } + /// + /// Adds a payload to the message. + /// + /// The payload. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(byte[] payload) { _payload = payload; return this; } + /// + /// Adds a payload to the message. + /// + /// The payload. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(IEnumerable payload) { if (payload == null) @@ -54,6 +151,11 @@ namespace MQTTnet return this; } + /// + /// Adds a payload to the message. + /// + /// The payload. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(Stream payload) { if (payload == null) @@ -65,6 +167,12 @@ namespace MQTTnet return WithPayload(payload, payload.Length - payload.Position); } + /// + /// Adds a payload to the message. + /// + /// The payload. + /// The stream length. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(Stream payload, long length) { if (payload == null) @@ -86,6 +194,11 @@ namespace MQTTnet return this; } + /// + /// Adds a payload to the message. + /// + /// The payload. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(string payload) { if (payload == null) @@ -98,12 +211,22 @@ namespace MQTTnet return this; } + /// + /// Adds the quality of service level to the message. + /// + /// The quality of service level. + /// A new instance of the class. public MqttApplicationMessageBuilder WithQualityOfServiceLevel(MqttQualityOfServiceLevel qualityOfServiceLevel) { _qualityOfServiceLevel = qualityOfServiceLevel; return this; } + /// + /// Adds the quality of service level to the message. + /// + /// The quality of service level. + /// A new instance of the class. public MqttApplicationMessageBuilder WithQualityOfServiceLevel(int qualityOfServiceLevel) { if (qualityOfServiceLevel < 0 || qualityOfServiceLevel > 2) @@ -114,24 +237,40 @@ namespace MQTTnet return WithQualityOfServiceLevel((MqttQualityOfServiceLevel)qualityOfServiceLevel); } + /// + /// Adds retain flag to the message. + /// + /// A new instance of the class. public MqttApplicationMessageBuilder WithRetainFlag(bool value = true) { _retain = value; return this; } + /// + /// Adds the quality of service level 0 (at least once) to the message. + /// + /// A new instance of the class. public MqttApplicationMessageBuilder WithAtLeastOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtLeastOnce; return this; } + /// + /// Adds the quality of service level 1 (at most once) to the message. + /// + /// A new instance of the class. public MqttApplicationMessageBuilder WithAtMostOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; return this; } + /// + /// Adds the quality of service level 2 (exactly once) to the message. + /// + /// A new instance of the class. public MqttApplicationMessageBuilder WithExactlyOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.ExactlyOnce; @@ -139,8 +278,12 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the user property to the message. + /// Hint: MQTT 5 feature only. /// + /// The property name. + /// The property value. + /// A new instance of the class. public MqttApplicationMessageBuilder WithUserProperty(string name, string value) { if (_userProperties == null) @@ -153,8 +296,10 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the content type to the message. + /// Hint: MQTT 5 feature only. /// + /// A new instance of the class. public MqttApplicationMessageBuilder WithContentType(string contentType) { _contentType = contentType; @@ -162,8 +307,11 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the response topic to the message. + /// Hint: MQTT 5 feature only. /// + /// The response topic. + /// A new instance of the class. public MqttApplicationMessageBuilder WithResponseTopic(string responseTopic) { _responseTopic = responseTopic; @@ -171,8 +319,11 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the correlation data to the message. + /// Hint: MQTT 5 feature only. /// + /// The correlation data. + /// A new instance of the class. public MqttApplicationMessageBuilder WithCorrelationData(byte[] correlationData) { _correlationData = correlationData; @@ -180,8 +331,11 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the topic alias to the message. + /// Hint: MQTT 5 feature only. /// + /// The topic alias. + /// A new instance of the class. public MqttApplicationMessageBuilder WithTopicAlias(ushort topicAlias) { _topicAlias = topicAlias; @@ -189,8 +343,11 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the subscription identifier to the message. + /// Hint: MQTT 5 feature only. /// + /// The subscription identifier. + /// A new instance of the class. public MqttApplicationMessageBuilder WithSubscriptionIdentifier(uint subscriptionIdentifier) { if (_subscriptionIdentifiers == null) @@ -203,8 +360,11 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the message expiry interval to the message. + /// Hint: MQTT 5 feature only. /// + /// The message expiry interval. + /// A new instance of the class. public MqttApplicationMessageBuilder WithMessageExpiryInterval(uint messageExpiryInterval) { _messageExpiryInterval = messageExpiryInterval; @@ -212,14 +372,21 @@ namespace MQTTnet } /// - /// This is only supported when using MQTTv5. + /// Adds the payload format indicator to the message. + /// Hint: MQTT 5 feature only. /// + /// The payload format indicator. + /// A new instance of the class. public MqttApplicationMessageBuilder WithPayloadFormatIndicator(MqttPayloadFormatIndicator payloadFormatIndicator) { _payloadFormatIndicator = payloadFormatIndicator; return this; } + /// + /// Builds the message. + /// + /// A new instance of the class. public MqttApplicationMessage Build() { if (!_topicAlias.HasValue && string.IsNullOrEmpty(_topic)) diff --git a/Source/MQTTnet/MqttApplicationMessageExtensions.cs b/Source/MQTTnet/MqttApplicationMessageExtensions.cs index dac9998..2619124 100644 --- a/Source/MQTTnet/MqttApplicationMessageExtensions.cs +++ b/Source/MQTTnet/MqttApplicationMessageExtensions.cs @@ -5,6 +5,11 @@ namespace MQTTnet { public static class MqttApplicationMessageExtensions { + /// + /// Converts the payload to a string if possible. + /// + /// The application message. + /// A string. public static string ConvertPayloadToString(this MqttApplicationMessage applicationMessage) { if (applicationMessage == null) throw new ArgumentNullException(nameof(applicationMessage)); diff --git a/Source/MQTTnet/MqttTopicFilter.cs b/Source/MQTTnet/MqttTopicFilter.cs index 66ea94a..fda60e0 100644 --- a/Source/MQTTnet/MqttTopicFilter.cs +++ b/Source/MQTTnet/MqttTopicFilter.cs @@ -10,22 +10,38 @@ namespace MQTTnet public class MqttTopicFilter { + /// + /// Gets or sets the MQTT topic. + /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. + /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). + /// public string Topic { get; set; } + /// + /// Gets or sets the quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel QualityOfServiceLevel { get; set; } /// - /// This is only supported when using MQTTv5. + /// Gets or sets a value indicating whether to not send messages originating on this client (noLocal) or not. /// + /// Hint: MQTT 5 feature only. public bool? NoLocal { get; set; } /// - /// This is only supported when using MQTTv5. + /// Gets or sets a value indicating whether messages are retained as published or not. + /// Hint: MQTT 5 feature only. /// public bool? RetainAsPublished { get; set; } /// - /// This is only supported when using MQTTv5. + /// Gets or sets the retain handling. + /// Hint: MQTT 5 feature only. /// public MqttRetainHandling? RetainHandling { get; set; } diff --git a/Source/MQTTnet/MqttTopicFilterBuilder.cs b/Source/MQTTnet/MqttTopicFilterBuilder.cs index 712f25d..bcf6efd 100644 --- a/Source/MQTTnet/MqttTopicFilterBuilder.cs +++ b/Source/MQTTnet/MqttTopicFilterBuilder.cs @@ -11,39 +11,79 @@ namespace MQTTnet public class MqttTopicFilterBuilder { + /// + /// The quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// MqttQualityOfServiceLevel _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; + + /// + /// The MQTT topic. + /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. + /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). + /// string _topic; + /// + /// Adds a topic to the topic filter. + /// + /// The topic. + /// A new instance of the class. public MqttTopicFilterBuilder WithTopic(string topic) { _topic = topic; return this; } + /// + /// Adds the quality of service level to the topic filter. + /// + /// The quality of service level. + /// A new instance of the class. public MqttTopicFilterBuilder WithQualityOfServiceLevel(MqttQualityOfServiceLevel qualityOfServiceLevel) { _qualityOfServiceLevel = qualityOfServiceLevel; return this; } + /// + /// Adds the quality of service level 0 (at least once) to the topic filter. + /// + /// A new instance of the class. public MqttTopicFilterBuilder WithAtLeastOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtLeastOnce; return this; } + /// + /// Adds the quality of service level 1 (at most once) to the topic filter. + /// + /// A new instance of the class. public MqttTopicFilterBuilder WithAtMostOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; return this; } + /// + /// Adds the quality of service level 2 (exactly once) to the topic filter. + /// + /// A new instance of the class. public MqttTopicFilterBuilder WithExactlyOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.ExactlyOnce; return this; } + /// + /// Builds the topic filter. + /// + /// A new instance of the class. public MqttTopicFilter Build() { if (string.IsNullOrEmpty(_topic)) diff --git a/Source/MQTTnet/Server/IMqttServerFactory.cs b/Source/MQTTnet/Server/IMqttServerFactory.cs index 39efaa3..05090bb 100644 --- a/Source/MQTTnet/Server/IMqttServerFactory.cs +++ b/Source/MQTTnet/Server/IMqttServerFactory.cs @@ -7,14 +7,37 @@ namespace MQTTnet.Server { public interface IMqttServerFactory { + /// + /// Gets the default server adapters. + /// IList> DefaultServerAdapters { get; } + /// + /// Creates a new default MQTT server. + /// + /// A new . IMqttServer CreateMqttServer(); + /// + /// Creates a new default MQTT server. + /// + /// The logger. + /// A new . IMqttServer CreateMqttServer(IMqttNetLogger logger); + /// + /// Creates a new default MQTT server. + /// + /// The adapters. + /// A new . IMqttServer CreateMqttServer(IEnumerable adapters); + /// + /// Creates a new default MQTT server. + /// + /// The adapters. + /// The logger. + /// A new . IMqttServer CreateMqttServer(IEnumerable adapters, IMqttNetLogger logger); } } \ No newline at end of file From 5eab337e13d909e462d3d6a7b17f64133ddc7d47 Mon Sep 17 00:00:00 2001 From: SeppPenner Date: Fri, 15 Jan 2021 19:41:45 +0100 Subject: [PATCH 2/5] Removed not needed comments on client side (Server side is still missing). --- .../Connecting/IMqttClientConnectedHandler.cs | 5 - .../MqttClientAuthenticateResult.cs | 33 ---- .../IMqttClientDisconnectedHandler.cs | 5 - .../MqttClientDisconnectedEventArgs.cs | 6 - ...ttExtendedAuthenticationExchangeHandler.cs | 5 - ...ttExtendedAuthenticationExchangeContext.cs | 3 - Source/MQTTnet/Client/IMqttClient.cs | 32 ---- Source/MQTTnet/Client/IMqttClientFactory.cs | 45 ----- .../Client/Options/IMqttClientOptions.cs | 18 -- ...entCertificateValidationCallbackContext.cs | 12 -- .../Client/Options/MqttClientOptions.cs | 18 -- .../Options/MqttClientOptionsBuilder.cs | 167 ------------------ .../Publishing/MqttClientPublishResult.cs | 3 - .../IMqttApplicationMessageReceivedHandler.cs | 5 - .../MqttClientSubscribeOptionsBuilder.cs | 33 ---- .../MqttClientUnsubscribeOptionsBuilder.cs | 14 -- 16 files changed, 404 deletions(-) diff --git a/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs b/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs index 233ee57..8b7be27 100644 --- a/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs +++ b/Source/MQTTnet/Client/Connecting/IMqttClientConnectedHandler.cs @@ -4,11 +4,6 @@ namespace MQTTnet.Client.Connecting { public interface IMqttClientConnectedHandler { - /// - /// Handles the events when a client gets connected. - /// - /// The event args. - /// A representing any asynchronous operation. Task HandleConnectedAsync(MqttClientConnectedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs b/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs index dfcaaff..ecb1293 100644 --- a/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs +++ b/Source/MQTTnet/Client/Connecting/MqttClientAuthenticateResult.cs @@ -13,24 +13,12 @@ namespace MQTTnet.Client.Connecting /// public MqttClientConnectResultCode ResultCode { get; set; } - /// - /// Gets or sets a value indicating whether the session is present or not. - /// public bool IsSessionPresent { get; set; } - /// - /// Gets or sets a value indicating whether wildcard subscriptions are available. - /// public bool? WildcardSubscriptionAvailable { get; set; } - /// - /// Gets or sets a value indicating whether retained messages are available. - /// public bool? RetainAvailable { get; set; } - /// - /// Gets or sets the assigned client identifier. - /// public string AssignedClientIdentifier { get; set; } /// @@ -45,9 +33,6 @@ namespace MQTTnet.Client.Connecting /// public byte[] AuthenticationData { get; set; } - /// - /// Gets or sets the maximum packet size. - /// public uint? MaximumPacketSize { get; set; } /// @@ -56,14 +41,8 @@ namespace MQTTnet.Client.Connecting /// public string ReasonString { get; set; } - /// - /// Gets or sets the receive maximum. - /// public ushort? ReceiveMaximum { get; set; } - /// - /// Gets or sets the maximum quality od service level. - /// public MqttQualityOfServiceLevel MaximumQoS { get; set; } /// @@ -72,24 +51,12 @@ namespace MQTTnet.Client.Connecting /// public string ResponseInformation { get; set; } - /// - /// Gets or sets the topic alias maximum. - /// public ushort? TopicAliasMaximum { get; set; } - /// - /// Gets or sets the server reference. - /// public string ServerReference { get; set; } - /// - /// Gets or sets the server keep alive. - /// public ushort? ServerKeepAlive { get; set; } - /// - /// Gets or sets the session expiry interval. - /// public uint? SessionExpiryInterval { get; set; } /// diff --git a/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs b/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs index 81e0b9b..14347bf 100644 --- a/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs +++ b/Source/MQTTnet/Client/Disconnecting/IMqttClientDisconnectedHandler.cs @@ -4,11 +4,6 @@ namespace MQTTnet.Client.Disconnecting { public interface IMqttClientDisconnectedHandler { - /// - /// Handles the events when a client gets disconnected. - /// - /// The event args. - /// A representing any asynchronous operation. Task HandleDisconnectedAsync(MqttClientDisconnectedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs index aa02634..932f009 100644 --- a/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs +++ b/Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectedEventArgs.cs @@ -15,14 +15,8 @@ namespace MQTTnet.Client.Disconnecting ReasonCode = reason; } - /// - /// Gets a value indicating whether the client was connected or not. - /// public bool ClientWasConnected { get; } - /// - /// Gets the exception. - /// public Exception Exception { get; } /// diff --git a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs index 69a689c..8cd3542 100644 --- a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs +++ b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/IMqttExtendedAuthenticationExchangeHandler.cs @@ -4,11 +4,6 @@ namespace MQTTnet.Client.ExtendedAuthenticationExchange { public interface IMqttExtendedAuthenticationExchangeHandler { - /// - /// Handles the authentication request. - /// - /// The context. - /// A representing any asynchronous operation. Task HandleRequestAsync(MqttExtendedAuthenticationExchangeContext context); } } diff --git a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs index a83576d..082e9a8 100644 --- a/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs +++ b/Source/MQTTnet/Client/ExtendedAuthenticationExchange/MqttExtendedAuthenticationExchangeContext.cs @@ -53,9 +53,6 @@ namespace MQTTnet.Client.ExtendedAuthenticationExchange /// public List UserProperties { get; } - /// - /// Gets the client. - /// public IMqttClient Client { get; } } } diff --git a/Source/MQTTnet/Client/IMqttClient.cs b/Source/MQTTnet/Client/IMqttClient.cs index 95ee1d9..dbe005a 100644 --- a/Source/MQTTnet/Client/IMqttClient.cs +++ b/Source/MQTTnet/Client/IMqttClient.cs @@ -12,9 +12,6 @@ namespace MQTTnet.Client { public interface IMqttClient : IApplicationMessageReceiver, IApplicationMessagePublisher, IDisposable { - /// - /// Gets a value indicating whether the client is connected or not. - /// bool IsConnected { get; } /// @@ -35,27 +32,10 @@ namespace MQTTnet.Client /// IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } - /// - /// Connects the client to the server using the specified options. - /// - /// The options that can be used on connect. - /// A cancellation token to stop the task. - /// A result containing the authentication result information. Task ConnectAsync(IMqttClientOptions options, CancellationToken cancellationToken); - /// - /// Disconnects the client from the server. - /// - /// The options containing a disconnect reason. - /// A cancellation token to stop the task. - /// A representing any asynchronous operation. Task DisconnectAsync(MqttClientDisconnectOptions options, CancellationToken cancellationToken); - /// - /// Pings the server. - /// - /// A cancellation token to stop the task. - /// A representing any asynchronous operation. Task PingAsync(CancellationToken cancellationToken); /// @@ -67,20 +47,8 @@ namespace MQTTnet.Client /// A representing any asynchronous operation. Task SendExtendedAuthenticationExchangeDataAsync(MqttExtendedAuthenticationExchangeData data, CancellationToken cancellationToken); - /// - /// Subscribes the client to topics. - /// - /// The subscription options. - /// A cancellation token to stop the task. - /// A representing any asynchronous operation. Task SubscribeAsync(MqttClientSubscribeOptions options, CancellationToken cancellationToken); - /// - /// Unsubscribes the client from topics. - /// - /// The unsubscription options. - /// A cancellation token to stop the task. - /// A representing any asynchronous operation. Task UnsubscribeAsync(MqttClientUnsubscribeOptions options, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/IMqttClientFactory.cs b/Source/MQTTnet/Client/IMqttClientFactory.cs index 54707ff..4bbb79a 100644 --- a/Source/MQTTnet/Client/IMqttClientFactory.cs +++ b/Source/MQTTnet/Client/IMqttClientFactory.cs @@ -6,67 +6,22 @@ namespace MQTTnet.Client { public interface IMqttClientFactory { - /// - /// A method to tell the client to use the adapter factory. - /// - /// The client adapter factory. - /// A new . IMqttFactory UseClientAdapterFactory(IMqttClientAdapterFactory clientAdapterFactory); - /// - /// Creates a new low level MQTT client. - /// - /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(); - /// - /// Creates a new low level MQTT client. - /// - /// The logger. - /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttNetLogger logger); - /// - /// Creates a new low level MQTT client. - /// - /// The client adapter factory. - /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttClientAdapterFactory clientAdapterFactory); - /// - /// Creates a new low level MQTT client. - /// - /// The logger. - /// The client adapter factory. - /// A new . ILowLevelMqttClient CreateLowLevelMqttClient(IMqttNetLogger logger, IMqttClientAdapterFactory clientAdapterFactory); - /// - /// Creates a new MQTT client. - /// - /// A new . IMqttClient CreateMqttClient(); - /// - /// Creates a new MQTT client. - /// - /// The logger. - /// A new . IMqttClient CreateMqttClient(IMqttNetLogger logger); - /// - /// Creates a new MQTT client. - /// - /// The adapter factory. - /// A new . IMqttClient CreateMqttClient(IMqttClientAdapterFactory adapterFactory); - /// - /// Creates a new MQTT client. - /// - /// The logger. - /// The adapter factory. - /// A new . IMqttClient CreateMqttClient(IMqttNetLogger logger, IMqttClientAdapterFactory adapterFactory); } } \ No newline at end of file diff --git a/Source/MQTTnet/Client/Options/IMqttClientOptions.cs b/Source/MQTTnet/Client/Options/IMqttClientOptions.cs index 642a872..e159d99 100644 --- a/Source/MQTTnet/Client/Options/IMqttClientOptions.cs +++ b/Source/MQTTnet/Client/Options/IMqttClientOptions.cs @@ -24,29 +24,14 @@ namespace MQTTnet.Client.Options /// bool CleanSession { get; } - /// - /// Gets the credentials. - /// IMqttClientCredentials Credentials { get; } - /// - /// Gets the extended authentication exchange handler. - /// IMqttExtendedAuthenticationExchangeHandler ExtendedAuthenticationExchangeHandler { get; } - /// - /// Gets the protocol version. - /// MqttProtocolVersion ProtocolVersion { get; } - /// - /// Gets the channel options. - /// IMqttClientChannelOptions ChannelOptions { get; } - /// - /// Gets the timeout the communication uses. - /// TimeSpan CommunicationTimeout { get; } /// @@ -82,9 +67,6 @@ namespace MQTTnet.Client.Options /// byte[] AuthenticationData { get; } - /// - /// Gets the maximum packet size. - /// uint? MaximumPacketSize { get; } /// diff --git a/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs b/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs index 0a86301..3827f05 100644 --- a/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs +++ b/Source/MQTTnet/Client/Options/MqttClientCertificateValidationCallbackContext.cs @@ -5,24 +5,12 @@ namespace MQTTnet.Client.Options { public class MqttClientCertificateValidationCallbackContext { - /// - /// Gets or sets the certificate. - /// public X509Certificate Certificate { get; set; } - /// - /// Gets or sets the certificate chain. - /// public X509Chain Chain { get; set; } - /// - /// Gets or sets the SSL policy errors. - /// public SslPolicyErrors SslPolicyErrors { get; set; } - /// - /// Gets or sets the client options. - /// public IMqttClientChannelOptions ClientOptions { get; set; } } } diff --git a/Source/MQTTnet/Client/Options/MqttClientOptions.cs b/Source/MQTTnet/Client/Options/MqttClientOptions.cs index e150e49..6332a03 100644 --- a/Source/MQTTnet/Client/Options/MqttClientOptions.cs +++ b/Source/MQTTnet/Client/Options/MqttClientOptions.cs @@ -24,29 +24,14 @@ namespace MQTTnet.Client.Options /// public bool CleanSession { get; set; } = true; - /// - /// Gets or sets the credentials. - /// public IMqttClientCredentials Credentials { get; set; } - /// - /// Gets or sets the extended authentication exchange handler. - /// public IMqttExtendedAuthenticationExchangeHandler ExtendedAuthenticationExchangeHandler { get; set; } - /// - /// Gets or sets the protocol version. - /// public MqttProtocolVersion ProtocolVersion { get; set; } = MqttProtocolVersion.V311; - /// - /// Gets or sets the channel options. - /// public IMqttClientChannelOptions ChannelOptions { get; set; } - /// - /// Gets or sets the timeout the communication uses. - /// public TimeSpan CommunicationTimeout { get; set; } = TimeSpan.FromSeconds(10); /// @@ -82,9 +67,6 @@ namespace MQTTnet.Client.Options /// public byte[] AuthenticationData { get; set; } - /// - /// Gets or sets the maximum packet size. - /// public uint? MaximumPacketSize { get; set; } /// diff --git a/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs b/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs index 402f28a..68d1aa3 100644 --- a/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs @@ -17,11 +17,6 @@ namespace MQTTnet.Client.Options MqttClientOptionsBuilderTlsParameters _tlsParameters; MqttClientWebSocketProxyOptions _proxyOptions; - /// - /// Adds the protocol version to the MQTT client options. - /// - /// The protocol version. - /// A new instance of the class. public MqttClientOptionsBuilder WithProtocolVersion(MqttProtocolVersion value) { if (value == MqttProtocolVersion.Unknown) @@ -33,88 +28,47 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds the communication timeout to the MQTT client options. - /// - /// The timeout. - /// A new instance of the class. public MqttClientOptionsBuilder WithCommunicationTimeout(TimeSpan value) { _options.CommunicationTimeout = value; return this; } - /// - /// Adds the clean session flag to the MQTT client options. - /// - /// The clean session flag. - /// A new instance of the class. public MqttClientOptionsBuilder WithCleanSession(bool value = true) { _options.CleanSession = value; return this; } - /// - /// Adds the keep alive send interval to the MQTT client options. - /// - /// The keep alive interval. - /// A new instance of the class. [Obsolete("This method is no longer supported. The client will send ping requests just before the keep alive interval is going to elapse. As per MQTT RFC the serve has to wait 1.5 times the interval so we don't need this anymore.")] public MqttClientOptionsBuilder WithKeepAliveSendInterval(TimeSpan value) { return this; } - /// - /// Adds no keep alive period to the MQTT client options. - /// - /// A new instance of the class. public MqttClientOptionsBuilder WithNoKeepAlive() { return WithKeepAlivePeriod(TimeSpan.Zero); } - /// - /// Adds the keep alive period to the MQTT client options. - /// - /// The keep alive period. - /// A new instance of the class. public MqttClientOptionsBuilder WithKeepAlivePeriod(TimeSpan value) { _options.KeepAlivePeriod = value; return this; } - /// - /// Adds the client identifier to the MQTT client options. - /// - /// The client identifier. - /// A new instance of the class. public MqttClientOptionsBuilder WithClientId(string value) { _options.ClientId = value; return this; } - /// - /// Adds the will message to the MQTT client options. - /// - /// The will message. - /// A new instance of the class. public MqttClientOptionsBuilder WithWillMessage(MqttApplicationMessage value) { _options.WillMessage = value; return this; } - /// - /// Adds the authentication to the MQTT client options. - /// Hint: MQTT 5 feature only. - /// - /// The authentication method. - /// The data. - /// A new instance of the class. public MqttClientOptionsBuilder WithAuthentication(string method, byte[] data) { _options.AuthenticationMethod = method; @@ -122,92 +76,48 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds the will delay interval to the MQTT client options. - /// - /// The will delay interval. - /// A new instance of the class. public MqttClientOptionsBuilder WithWillDelayInterval(uint? willDelayInterval) { _options.WillDelayInterval = willDelayInterval; return this; } - /// - /// Adds the topic alias maximum to the MQTT client options. - /// - /// The topic alias maximum. - /// A new instance of the class. public MqttClientOptionsBuilder WithTopicAliasMaximum(ushort? topicAliasMaximum) { _options.TopicAliasMaximum = topicAliasMaximum; return this; } - /// - /// Adds the maximum packet size to the MQTT client options. - /// - /// The maximum packet size. - /// A new instance of the class. public MqttClientOptionsBuilder WithMaximumPacketSize(uint? maximumPacketSize) { _options.MaximumPacketSize = maximumPacketSize; return this; } - /// - /// Adds the receive maximum to the MQTT client options. - /// - /// The receive maximum. - /// A new instance of the class. public MqttClientOptionsBuilder WithReceiveMaximum(ushort? receiveMaximum) { _options.ReceiveMaximum = receiveMaximum; return this; } - /// - /// Adds the request problem information to the MQTT client options. - /// Hint: MQTT 5 feature only. - /// - /// The request problem information. - /// A new instance of the class. public MqttClientOptionsBuilder WithRequestProblemInformation(bool? requestProblemInformation = true) { _options.RequestProblemInformation = requestProblemInformation; return this; } - /// - /// Adds the request response information to the MQTT client options. - /// Hint: MQTT 5 feature only. - /// - /// The request response information. - /// A new instance of the class. public MqttClientOptionsBuilder WithRequestResponseInformation(bool? requestResponseInformation = true) { _options.RequestResponseInformation = requestResponseInformation; return this; } - /// - /// Adds the session expiry interval to the MQTT client options. - /// - /// The session expiry interval. - /// A new instance of the class. public MqttClientOptionsBuilder WithSessionExpiryInterval(uint? sessionExpiryInterval) { _options.SessionExpiryInterval = sessionExpiryInterval; return this; } - /// - /// Adds the user property to the MQTT client options. - /// Hint: MQTT 5 feature only. - /// - /// The user property name. - /// The user property value. - /// A new instance of the class. public MqttClientOptionsBuilder WithUserProperty(string name, string value) { if (name is null) throw new ArgumentNullException(nameof(name)); @@ -222,12 +132,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds the credentials to the MQTT client options. - /// - /// The user name. - /// The password. - /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(string username, string password = null) { byte[] passwordBuffer = null; @@ -240,12 +144,6 @@ namespace MQTTnet.Client.Options return WithCredentials(username, passwordBuffer); } - /// - /// Adds the credentials to the MQTT client options. - /// - /// The user name. - /// The password. - /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(string username, byte[] password = null) { _options.Credentials = new MqttClientCredentials @@ -257,11 +155,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds the credentials to the MQTT client options. - /// - /// The credentials. - /// A new instance of the class. public MqttClientOptionsBuilder WithCredentials(IMqttClientCredentials credentials) { _options.Credentials = credentials; @@ -269,23 +162,12 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a extended authentication exchange handler to the MQTT client options. - /// - /// The handler. - /// A new instance of the class. public MqttClientOptionsBuilder WithExtendedAuthenticationExchangeHandler(IMqttExtendedAuthenticationExchangeHandler handler) { _options.ExtendedAuthenticationExchangeHandler = handler; return this; } - /// - /// Adds a TCP server connection to the MQTT client options. - /// - /// The server. - /// The port. - /// A new instance of the class. public MqttClientOptionsBuilder WithTcpServer(string server, int? port = null) { _tcpOptions = new MqttClientTcpOptions @@ -297,11 +179,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a TCP server connection to the MQTT client options. - /// - /// The options builder. - /// A new instance of the class. // TODO: Consider creating _MqttClientTcpOptionsBuilder_ as overload. public MqttClientOptionsBuilder WithTcpServer(Action optionsBuilder) { @@ -313,16 +190,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a proxy connection to the MQTT client options. - /// - /// The address. - /// The user name. - /// The password. - /// The domain. - /// The bypass on local flag. - /// The bypass list. - /// A new instance of the class. public MqttClientOptionsBuilder WithProxy(string address, string username = null, string password = null, string domain = null, bool bypassOnLocal = false, string[] bypassList = null) { _proxyOptions = new MqttClientWebSocketProxyOptions @@ -338,11 +205,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a proxy connection to the MQTT client options. - /// - /// The options builder. - /// A new instance of the class. public MqttClientOptionsBuilder WithProxy(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -352,12 +214,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a web socket server to the MQTT client options. - /// - /// The uri. - /// The parameters. - /// A new instance of the class. public MqttClientOptionsBuilder WithWebSocketServer(string uri, MqttClientOptionsBuilderWebSocketParameters parameters = null) { _webSocketOptions = new MqttClientWebSocketOptions @@ -370,11 +226,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds a web socket server to the MQTT client options. - /// - /// The options builder. - /// A new instance of the class. public MqttClientOptionsBuilder WithWebSocketServer(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -385,31 +236,17 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Adds TLS to the MQTT client options. - /// - /// The parameters. - /// A new instance of the class. public MqttClientOptionsBuilder WithTls(MqttClientOptionsBuilderTlsParameters parameters) { _tlsParameters = parameters; return this; } - /// - /// Adds TLS to the MQTT client options. - /// - /// A new instance of the class. public MqttClientOptionsBuilder WithTls() { return WithTls(new MqttClientOptionsBuilderTlsParameters { UseTls = true }); } - /// - /// Adds TLS to the MQTT client options. - /// - /// The options builder. - /// A new instance of the class. public MqttClientOptionsBuilder WithTls(Action optionsBuilder) { if (optionsBuilder == null) throw new ArgumentNullException(nameof(optionsBuilder)); @@ -419,10 +256,6 @@ namespace MQTTnet.Client.Options return this; } - /// - /// Builds the MQTT client options. - /// - /// The . public IMqttClientOptions Build() { if (_tcpOptions == null && _webSocketOptions == null) diff --git a/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs b/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs index 0a51c98..429f130 100644 --- a/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs +++ b/Source/MQTTnet/Client/Publishing/MqttClientPublishResult.cs @@ -6,9 +6,6 @@ namespace MQTTnet.Client.Publishing { public class MqttClientPublishResult { - /// - /// Gets or sets the packet identifier. - /// public ushort? PacketIdentifier { get; set; } /// diff --git a/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs b/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs index 199adba..3ea7317 100644 --- a/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs +++ b/Source/MQTTnet/Client/Receiving/IMqttApplicationMessageReceivedHandler.cs @@ -4,11 +4,6 @@ namespace MQTTnet.Client.Receiving { public interface IMqttApplicationMessageReceivedHandler { - /// - /// Handles the application message received event. - /// - /// The event args. - /// A representing any asynchronous operation. Task HandleApplicationMessageReceivedAsync(MqttApplicationMessageReceivedEventArgs eventArgs); } } diff --git a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs index 96e6c5d..14d2ad6 100644 --- a/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsBuilder.cs @@ -31,26 +31,12 @@ namespace MQTTnet.Client.Subscribing return this; } - /// - /// Adds the subscription identifier to the subscribe options. - /// - /// The subscription identifier. - /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithSubscriptionIdentifier(uint? subscriptionIdentifier) { _subscribeOptions.SubscriptionIdentifier = subscriptionIdentifier; return this; } - /// - /// Adds a topic filter to the subscribe options. - /// - /// The topic. - /// The quality of service level. - /// A value indicating whether to not send messages originating on this client (noLocal) or not. - /// A value indicating whether messages are retained as published or not. - /// The retain handling. - /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter( string topic, MqttQualityOfServiceLevel qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce, @@ -68,11 +54,6 @@ namespace MQTTnet.Client.Subscribing }); } - /// - /// Adds the topic filter to the subscribe options. - /// - /// The topic filter builder. - /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(Action topicFilterBuilder) { if (topicFilterBuilder == null) throw new ArgumentNullException(nameof(topicFilterBuilder)); @@ -83,11 +64,6 @@ namespace MQTTnet.Client.Subscribing return WithTopicFilter(internalTopicFilterBuilder); } - /// - /// Adds the topic filter to the subscribe options. - /// - /// The topic filter builder. - /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(MqttTopicFilterBuilder topicFilterBuilder) { if (topicFilterBuilder == null) throw new ArgumentNullException(nameof(topicFilterBuilder)); @@ -95,11 +71,6 @@ namespace MQTTnet.Client.Subscribing return WithTopicFilter(topicFilterBuilder.Build()); } - /// - /// Adds the topic filter to the subscribe options. - /// - /// The topic filter. - /// A new instance of the class. public MqttClientSubscribeOptionsBuilder WithTopicFilter(MqttTopicFilter topicFilter) { if (topicFilter == null) throw new ArgumentNullException(nameof(topicFilter)); @@ -114,10 +85,6 @@ namespace MQTTnet.Client.Subscribing return this; } - /// - /// Builds the subscription options. - /// - /// A new instance of the class. public MqttClientSubscribeOptions Build() { return _subscribeOptions; diff --git a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs index 56a1997..a7f022e 100644 --- a/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs +++ b/Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsBuilder.cs @@ -43,11 +43,6 @@ namespace MQTTnet.Client.Unsubscribing return this; } - /// - /// Adds the topic filter to the unsubscribe options. - /// - /// The topic. - /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithTopicFilter(string topic) { if (topic is null) throw new ArgumentNullException(nameof(topic)); @@ -62,11 +57,6 @@ namespace MQTTnet.Client.Unsubscribing return this; } - /// - /// Adds the topic filter to the unsubscribe options. - /// - /// The topic filter. - /// A new instance of the class. public MqttClientUnsubscribeOptionsBuilder WithTopicFilter(MqttTopicFilter topicFilter) { if (topicFilter is null) throw new ArgumentNullException(nameof(topicFilter)); @@ -74,10 +64,6 @@ namespace MQTTnet.Client.Unsubscribing return WithTopicFilter(topicFilter.Topic); } - /// - /// Builds the unsubscription options. - /// - /// A new instance of the class. public MqttClientUnsubscribeOptions Build() { return _unsubscribeOptions; From bba04e2b5ddb5b832d8360295f23dc2390f52010 Mon Sep 17 00:00:00 2001 From: SeppPenner Date: Fri, 15 Jan 2021 20:34:33 +0100 Subject: [PATCH 3/5] Updated all code comments, should be ok now. --- .../IManagedMqttClient.cs | 59 -------------- .../TopicGeneration/TopicGenerationContext.cs | 8 ++ .../MQTTnet/IApplicationMessagePublisher.cs | 6 -- Source/MQTTnet/IMqttFactory.cs | 6 -- .../MQTTnet/MqttApplicationMessageBuilder.cs | 61 --------------- .../MqttApplicationMessageExtensions.cs | 5 -- ...MqttApplicationMessageReceivedEventArgs.cs | 4 + Source/MQTTnet/MqttTopicFilterBuilder.cs | 26 ------- .../Server/CheckSubscriptionsResult.cs | 8 ++ Source/MQTTnet/Server/IMqttClientSession.cs | 4 + Source/MQTTnet/Server/IMqttServerFactory.cs | 23 ------ Source/MQTTnet/Server/IMqttServerOptions.cs | 4 + .../Server/IMqttServerPersistedSession.cs | 12 +++ ...qttApplicationMessageInterceptorContext.cs | 4 + ...qttClientMessageQueueInterceptorContext.cs | 8 ++ .../Server/MqttConnectionValidatorContext.cs | 76 ++++++++++++++++++- .../Server/MqttQueuedApplicationMessage.cs | 8 ++ .../MqttServerClientConnectedEventArgs.cs | 4 + .../MqttServerClientDisconnectedEventArgs.cs | 6 +- ...qttServerClientSubscribedTopicEventArgs.cs | 8 ++ ...tServerClientUnsubscribedTopicEventArgs.cs | 8 ++ Source/MQTTnet/Server/MqttServerOptions.cs | 4 + .../MqttSubscriptionInterceptorContext.cs | 8 ++ .../MqttUnsubscriptionInterceptorContext.cs | 9 +++ .../Server/Status/IMqttClientStatus.cs | 4 + .../Server/Status/IMqttSessionStatus.cs | 4 + .../MQTTnet/Server/Status/MqttClientStatus.cs | 4 + .../Server/Status/MqttSessionStatus.cs | 4 + 28 files changed, 197 insertions(+), 188 deletions(-) diff --git a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs index 4e06eaf..720ed12 100644 --- a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs +++ b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs @@ -16,95 +16,36 @@ namespace MQTTnet.Extensions.ManagedClient /// IMqttClient InternalClient { get; } - /// - /// Gets a value indicating whether the client is started or not. - /// bool IsStarted { get; } - /// - /// Gets a value indicating whether the client is connected or not. - /// bool IsConnected { get; } - /// - /// Gets a pending application message count. - /// int PendingApplicationMessagesCount { get; } - /// - /// Gets the MQTT client options. - /// IManagedMqttClientOptions Options { get; } - /// - /// Gets or sets the connected handler. - /// IMqttClientConnectedHandler ConnectedHandler { get; set; } - /// - /// Gets or sets the disconnected handler. - /// IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } - /// - /// Gets or sets the application message process handler. - /// IApplicationMessageProcessedHandler ApplicationMessageProcessedHandler { get; set; } - /// - /// Gets or sets the application message skipped handler. - /// IApplicationMessageSkippedHandler ApplicationMessageSkippedHandler { get; set; } - /// - /// Gets or sets the connecting failed handler. - /// IConnectingFailedHandler ConnectingFailedHandler { get; set; } - /// - /// Gets or sets the synchronizing subscriptions failed handler. - /// ISynchronizingSubscriptionsFailedHandler SynchronizingSubscriptionsFailedHandler { get; set; } - /// - /// Starts the client. - /// - /// The options. - /// A representing any asynchronous operation. Task StartAsync(IManagedMqttClientOptions options); - /// - /// Stops the client. - /// - /// A representing any asynchronous operation. Task StopAsync(); - /// - /// Pings the server. - /// - /// A token to cancel the task. - /// A representing any asynchronous operation. Task PingAsync(CancellationToken cancellationToken); - /// - /// Subscribes the client. - /// - /// The topic filters. - /// A representing any asynchronous operation. Task SubscribeAsync(IEnumerable topicFilters); - /// - /// Unsubscribes the client. - /// - /// The topics. - /// A representing any asynchronous operation. Task UnsubscribeAsync(IEnumerable topics); - /// - /// Publishes a message from the client. - /// - /// The application messages. - /// A representing any asynchronous operation. Task PublishAsync(ManagedMqttApplicationMessage applicationMessages); } } \ No newline at end of file diff --git a/Source/MQTTnet.Extensions.Rpc/Options/TopicGeneration/TopicGenerationContext.cs b/Source/MQTTnet.Extensions.Rpc/Options/TopicGeneration/TopicGenerationContext.cs index cd82c52..39110bb 100644 --- a/Source/MQTTnet.Extensions.Rpc/Options/TopicGeneration/TopicGenerationContext.cs +++ b/Source/MQTTnet.Extensions.Rpc/Options/TopicGeneration/TopicGenerationContext.cs @@ -7,6 +7,14 @@ namespace MQTTnet.Extensions.Rpc.Options.TopicGeneration { public string MethodName { get; set; } + /// + /// Gets or sets the quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel QualityOfServiceLevel { get; set; } public IMqttClient MqttClient { get; set; } diff --git a/Source/MQTTnet/IApplicationMessagePublisher.cs b/Source/MQTTnet/IApplicationMessagePublisher.cs index aa3caae..bf17718 100644 --- a/Source/MQTTnet/IApplicationMessagePublisher.cs +++ b/Source/MQTTnet/IApplicationMessagePublisher.cs @@ -6,12 +6,6 @@ namespace MQTTnet { public interface IApplicationMessagePublisher { - /// - /// Publishes a new application message to the server. - /// - /// The application message. - /// A cancellation token to stop the task. - /// A representing any asynchronous operation. Task PublishAsync(MqttApplicationMessage applicationMessage, CancellationToken cancellationToken); } } diff --git a/Source/MQTTnet/IMqttFactory.cs b/Source/MQTTnet/IMqttFactory.cs index b68e27a..8c0e5af 100644 --- a/Source/MQTTnet/IMqttFactory.cs +++ b/Source/MQTTnet/IMqttFactory.cs @@ -7,14 +7,8 @@ namespace MQTTnet { public interface IMqttFactory : IMqttClientFactory, IMqttServerFactory { - /// - /// Gets the default logger. - /// IMqttNetLogger DefaultLogger { get; } - /// - /// Gets the properties. - /// IDictionary Properties { get; } } } diff --git a/Source/MQTTnet/MqttApplicationMessageBuilder.cs b/Source/MQTTnet/MqttApplicationMessageBuilder.cs index e03d259..f2fc0cd 100644 --- a/Source/MQTTnet/MqttApplicationMessageBuilder.cs +++ b/Source/MQTTnet/MqttApplicationMessageBuilder.cs @@ -106,33 +106,18 @@ namespace MQTTnet /// Hint: MQTT 5 feature only. private List _userProperties; - /// - /// Adds a topic to the message. - /// - /// The topic. - /// A new instance of the class. public MqttApplicationMessageBuilder WithTopic(string topic) { _topic = topic; return this; } - /// - /// Adds a payload to the message. - /// - /// The payload. - /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(byte[] payload) { _payload = payload; return this; } - /// - /// Adds a payload to the message. - /// - /// The payload. - /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(IEnumerable payload) { if (payload == null) @@ -151,11 +136,6 @@ namespace MQTTnet return this; } - /// - /// Adds a payload to the message. - /// - /// The payload. - /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(Stream payload) { if (payload == null) @@ -167,12 +147,6 @@ namespace MQTTnet return WithPayload(payload, payload.Length - payload.Position); } - /// - /// Adds a payload to the message. - /// - /// The payload. - /// The stream length. - /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(Stream payload, long length) { if (payload == null) @@ -194,11 +168,6 @@ namespace MQTTnet return this; } - /// - /// Adds a payload to the message. - /// - /// The payload. - /// A new instance of the class. public MqttApplicationMessageBuilder WithPayload(string payload) { if (payload == null) @@ -211,22 +180,12 @@ namespace MQTTnet return this; } - /// - /// Adds the quality of service level to the message. - /// - /// The quality of service level. - /// A new instance of the class. public MqttApplicationMessageBuilder WithQualityOfServiceLevel(MqttQualityOfServiceLevel qualityOfServiceLevel) { _qualityOfServiceLevel = qualityOfServiceLevel; return this; } - /// - /// Adds the quality of service level to the message. - /// - /// The quality of service level. - /// A new instance of the class. public MqttApplicationMessageBuilder WithQualityOfServiceLevel(int qualityOfServiceLevel) { if (qualityOfServiceLevel < 0 || qualityOfServiceLevel > 2) @@ -237,40 +196,24 @@ namespace MQTTnet return WithQualityOfServiceLevel((MqttQualityOfServiceLevel)qualityOfServiceLevel); } - /// - /// Adds retain flag to the message. - /// - /// A new instance of the class. public MqttApplicationMessageBuilder WithRetainFlag(bool value = true) { _retain = value; return this; } - /// - /// Adds the quality of service level 0 (at least once) to the message. - /// - /// A new instance of the class. public MqttApplicationMessageBuilder WithAtLeastOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtLeastOnce; return this; } - /// - /// Adds the quality of service level 1 (at most once) to the message. - /// - /// A new instance of the class. public MqttApplicationMessageBuilder WithAtMostOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; return this; } - /// - /// Adds the quality of service level 2 (exactly once) to the message. - /// - /// A new instance of the class. public MqttApplicationMessageBuilder WithExactlyOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.ExactlyOnce; @@ -383,10 +326,6 @@ namespace MQTTnet return this; } - /// - /// Builds the message. - /// - /// A new instance of the class. public MqttApplicationMessage Build() { if (!_topicAlias.HasValue && string.IsNullOrEmpty(_topic)) diff --git a/Source/MQTTnet/MqttApplicationMessageExtensions.cs b/Source/MQTTnet/MqttApplicationMessageExtensions.cs index 2619124..dac9998 100644 --- a/Source/MQTTnet/MqttApplicationMessageExtensions.cs +++ b/Source/MQTTnet/MqttApplicationMessageExtensions.cs @@ -5,11 +5,6 @@ namespace MQTTnet { public static class MqttApplicationMessageExtensions { - /// - /// Converts the payload to a string if possible. - /// - /// The application message. - /// A string. public static string ConvertPayloadToString(this MqttApplicationMessage applicationMessage) { if (applicationMessage == null) throw new ArgumentNullException(nameof(applicationMessage)); diff --git a/Source/MQTTnet/MqttApplicationMessageReceivedEventArgs.cs b/Source/MQTTnet/MqttApplicationMessageReceivedEventArgs.cs index ed46305..ac307de 100644 --- a/Source/MQTTnet/MqttApplicationMessageReceivedEventArgs.cs +++ b/Source/MQTTnet/MqttApplicationMessageReceivedEventArgs.cs @@ -10,6 +10,10 @@ namespace MQTTnet ApplicationMessage = applicationMessage ?? throw new ArgumentNullException(nameof(applicationMessage)); } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } public MqttApplicationMessage ApplicationMessage { get; } diff --git a/Source/MQTTnet/MqttTopicFilterBuilder.cs b/Source/MQTTnet/MqttTopicFilterBuilder.cs index bcf6efd..9b4b7ab 100644 --- a/Source/MQTTnet/MqttTopicFilterBuilder.cs +++ b/Source/MQTTnet/MqttTopicFilterBuilder.cs @@ -28,62 +28,36 @@ namespace MQTTnet /// string _topic; - /// - /// Adds a topic to the topic filter. - /// - /// The topic. - /// A new instance of the class. public MqttTopicFilterBuilder WithTopic(string topic) { _topic = topic; return this; } - /// - /// Adds the quality of service level to the topic filter. - /// - /// The quality of service level. - /// A new instance of the class. public MqttTopicFilterBuilder WithQualityOfServiceLevel(MqttQualityOfServiceLevel qualityOfServiceLevel) { _qualityOfServiceLevel = qualityOfServiceLevel; return this; } - /// - /// Adds the quality of service level 0 (at least once) to the topic filter. - /// - /// A new instance of the class. public MqttTopicFilterBuilder WithAtLeastOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtLeastOnce; return this; } - /// - /// Adds the quality of service level 1 (at most once) to the topic filter. - /// - /// A new instance of the class. public MqttTopicFilterBuilder WithAtMostOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.AtMostOnce; return this; } - /// - /// Adds the quality of service level 2 (exactly once) to the topic filter. - /// - /// A new instance of the class. public MqttTopicFilterBuilder WithExactlyOnceQoS() { _qualityOfServiceLevel = MqttQualityOfServiceLevel.ExactlyOnce; return this; } - /// - /// Builds the topic filter. - /// - /// A new instance of the class. public MqttTopicFilter Build() { if (string.IsNullOrEmpty(_topic)) diff --git a/Source/MQTTnet/Server/CheckSubscriptionsResult.cs b/Source/MQTTnet/Server/CheckSubscriptionsResult.cs index b6e7dbd..eb66f17 100644 --- a/Source/MQTTnet/Server/CheckSubscriptionsResult.cs +++ b/Source/MQTTnet/Server/CheckSubscriptionsResult.cs @@ -8,6 +8,14 @@ namespace MQTTnet.Server public bool IsSubscribed { get; set; } + /// + /// Gets or sets the quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel QualityOfServiceLevel { get; set; } } } diff --git a/Source/MQTTnet/Server/IMqttClientSession.cs b/Source/MQTTnet/Server/IMqttClientSession.cs index d7db2b1..f522df6 100644 --- a/Source/MQTTnet/Server/IMqttClientSession.cs +++ b/Source/MQTTnet/Server/IMqttClientSession.cs @@ -4,6 +4,10 @@ namespace MQTTnet.Server { public interface IMqttClientSession { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; } Task StopAsync(); diff --git a/Source/MQTTnet/Server/IMqttServerFactory.cs b/Source/MQTTnet/Server/IMqttServerFactory.cs index 05090bb..39efaa3 100644 --- a/Source/MQTTnet/Server/IMqttServerFactory.cs +++ b/Source/MQTTnet/Server/IMqttServerFactory.cs @@ -7,37 +7,14 @@ namespace MQTTnet.Server { public interface IMqttServerFactory { - /// - /// Gets the default server adapters. - /// IList> DefaultServerAdapters { get; } - /// - /// Creates a new default MQTT server. - /// - /// A new . IMqttServer CreateMqttServer(); - /// - /// Creates a new default MQTT server. - /// - /// The logger. - /// A new . IMqttServer CreateMqttServer(IMqttNetLogger logger); - /// - /// Creates a new default MQTT server. - /// - /// The adapters. - /// A new . IMqttServer CreateMqttServer(IEnumerable adapters); - /// - /// Creates a new default MQTT server. - /// - /// The adapters. - /// The logger. - /// A new . IMqttServer CreateMqttServer(IEnumerable adapters, IMqttNetLogger logger); } } \ No newline at end of file diff --git a/Source/MQTTnet/Server/IMqttServerOptions.cs b/Source/MQTTnet/Server/IMqttServerOptions.cs index 233048e..cd0cd40 100644 --- a/Source/MQTTnet/Server/IMqttServerOptions.cs +++ b/Source/MQTTnet/Server/IMqttServerOptions.cs @@ -4,6 +4,10 @@ namespace MQTTnet.Server { public interface IMqttServerOptions { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; set; } bool EnablePersistentSessions { get; } diff --git a/Source/MQTTnet/Server/IMqttServerPersistedSession.cs b/Source/MQTTnet/Server/IMqttServerPersistedSession.cs index 9ca4076..a7b015e 100644 --- a/Source/MQTTnet/Server/IMqttServerPersistedSession.cs +++ b/Source/MQTTnet/Server/IMqttServerPersistedSession.cs @@ -5,14 +5,26 @@ namespace MQTTnet.Server { public interface IMqttServerPersistedSession { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; } IDictionary Items { get; } IList Subscriptions { get; } + /// + /// Gets the last will message. + /// In MQTT, you use the last will message feature to notify other clients about an ungracefully disconnected client. + /// MqttApplicationMessage WillMessage { get; } + /// + /// Gets the will delay interval. + /// This is the time between the client disconnect and the time the will message will be sent. + /// uint? WillDelayInterval { get; } DateTime? SessionExpiryTimestamp { get; } diff --git a/Source/MQTTnet/Server/MqttApplicationMessageInterceptorContext.cs b/Source/MQTTnet/Server/MqttApplicationMessageInterceptorContext.cs index cde9a85..f606a57 100644 --- a/Source/MQTTnet/Server/MqttApplicationMessageInterceptorContext.cs +++ b/Source/MQTTnet/Server/MqttApplicationMessageInterceptorContext.cs @@ -18,6 +18,10 @@ namespace MQTTnet.Server /// public IMqttNetScopedLogger Logger { get; } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } public MqttApplicationMessage ApplicationMessage { get; set; } diff --git a/Source/MQTTnet/Server/MqttClientMessageQueueInterceptorContext.cs b/Source/MQTTnet/Server/MqttClientMessageQueueInterceptorContext.cs index 209f8c0..881666e 100644 --- a/Source/MQTTnet/Server/MqttClientMessageQueueInterceptorContext.cs +++ b/Source/MQTTnet/Server/MqttClientMessageQueueInterceptorContext.cs @@ -20,6 +20,14 @@ namespace MQTTnet.Server public bool AcceptEnqueue { get; set; } = true; + /// + /// Gets or sets the supscription quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel SubscriptionQualityOfServiceLevel { get; set; } } } diff --git a/Source/MQTTnet/Server/MqttConnectionValidatorContext.cs b/Source/MQTTnet/Server/MqttConnectionValidatorContext.cs index 9a5b8b9..e9d6aeb 100644 --- a/Source/MQTTnet/Server/MqttConnectionValidatorContext.cs +++ b/Source/MQTTnet/Server/MqttConnectionValidatorContext.cs @@ -21,6 +21,10 @@ namespace MQTTnet.Server SessionItems = sessionItems; } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId => _connectPacket.ClientId; public string Endpoint => _clientAdapter.Endpoint; @@ -37,30 +41,88 @@ namespace MQTTnet.Server public string Password => Encoding.UTF8.GetString(RawPassword ?? new byte[0]); + /// + /// Gets or sets the will delay interval. + /// This is the time between the client disconnect and the time the will message will be sent. + /// public MqttApplicationMessage WillMessage => _connectPacket?.WillMessage; + /// + /// Gets or sets a value indicating whether clean sessions are used or not. + /// When a client connects to a broker it can connect using either a non persistent connection (clean session) or a persistent connection. + /// With a non persistent connection the broker doesn't store any subscription information or undelivered messages for the client. + /// This mode is ideal when the client only publishes messages. + /// It can also connect as a durable client using a persistent connection. + /// In this mode, the broker will store subscription information, and undelivered messages for the client. + /// public bool? CleanSession => _connectPacket?.CleanSession; + /// + /// Gets or sets the keep alive period. + /// The connection is normally left open by the client so that is can send and receive data at any time. + /// If no data flows over an open connection for a certain time period then the client will generate a PINGREQ and expect to receive a PINGRESP from the broker. + /// This message exchange confirms that the connection is open and working. + /// This period is known as the keep alive period. + /// public ushort? KeepAlivePeriod => _connectPacket?.KeepAlivePeriod; + /// + /// Gets or sets the user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List UserProperties => _connectPacket?.Properties?.UserProperties; + /// + /// Gets or sets the authentication data. + /// Hint: MQTT 5 feature only. + /// public byte[] AuthenticationData => _connectPacket?.Properties?.AuthenticationData; + /// + /// Gets or sets the authentication method. + /// Hint: MQTT 5 feature only. + /// public string AuthenticationMethod => _connectPacket?.Properties?.AuthenticationMethod; public uint? MaximumPacketSize => _connectPacket?.Properties?.MaximumPacketSize; + /// + /// Gets or sets the receive maximum. + /// This gives the maximum length of the receive messages. + /// public ushort? ReceiveMaximum => _connectPacket?.Properties?.ReceiveMaximum; + /// + /// Gets or sets the topic alias maximum. + /// This gives the maximum length of the topic alias. + /// public ushort? TopicAliasMaximum => _connectPacket?.Properties?.TopicAliasMaximum; + /// + /// Gets the request problem information. + /// Hint: MQTT 5 feature only. + /// public bool? RequestProblemInformation => _connectPacket?.Properties?.RequestProblemInformation; + /// + /// Gets the request response information. + /// Hint: MQTT 5 feature only. + /// public bool? RequestResponseInformation => _connectPacket?.Properties?.RequestResponseInformation; + /// + /// Gets the session expiry interval. + /// The time after a session expires when it's not actively used. + /// public uint? SessionExpiryInterval => _connectPacket?.Properties?.SessionExpiryInterval; + /// + /// Gets or sets the will delay interval. + /// This is the time between the client disconnect and the time the will message will be sent. + /// public uint? WillDelayInterval => _connectPacket?.Properties?.WillDelayInterval; /// @@ -79,14 +141,26 @@ namespace MQTTnet.Server } /// - /// This is used for MQTTv5 only. When a MQTTv3 client connects the enum value must be one which is + /// Gets or sets the reason code. When a MQTTv3 client connects the enum value must be one which is /// also supported in MQTTv3. Otherwise the connection attempt will fail because not all codes can be /// converted properly. + /// Hint: MQTT 5 feature only. /// public MqttConnectReasonCode ReasonCode { get; set; } = MqttConnectReasonCode.Success; + /// + /// Gets or sets the response user properties. + /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet. + /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber. + /// The feature is very similar to the HTTP header concept. + /// Hint: MQTT 5 feature only. + /// public List ResponseUserProperties { get; set; } + /// + /// Gets or sets the response authentication data. + /// Hint: MQTT 5 feature only. + /// public byte[] ResponseAuthenticationData { get; set; } public string AssignedClientIdentifier { get; set; } diff --git a/Source/MQTTnet/Server/MqttQueuedApplicationMessage.cs b/Source/MQTTnet/Server/MqttQueuedApplicationMessage.cs index 635894b..5ca163d 100644 --- a/Source/MQTTnet/Server/MqttQueuedApplicationMessage.cs +++ b/Source/MQTTnet/Server/MqttQueuedApplicationMessage.cs @@ -11,6 +11,14 @@ namespace MQTTnet.Server public bool IsRetainedMessage { get; set; } + /// + /// Gets or sets the subscription quality of service level. + /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message. + /// There are 3 QoS levels in MQTT: + /// - At most once (0): Message gets delivered no time, once or multiple times. + /// - At least once (1): Message gets delivered at least once (one time or more often). + /// - Exactly once (2): Message gets delivered exactly once (It's ensured that the message only comes once). + /// public MqttQualityOfServiceLevel SubscriptionQualityOfServiceLevel { get; set; } [Obsolete("Use 'SubscriptionQualityOfServiceLevel' instead.")] diff --git a/Source/MQTTnet/Server/MqttServerClientConnectedEventArgs.cs b/Source/MQTTnet/Server/MqttServerClientConnectedEventArgs.cs index 71c42c3..88f0c55 100644 --- a/Source/MQTTnet/Server/MqttServerClientConnectedEventArgs.cs +++ b/Source/MQTTnet/Server/MqttServerClientConnectedEventArgs.cs @@ -9,6 +9,10 @@ namespace MQTTnet.Server ClientId = clientId ?? throw new ArgumentNullException(nameof(clientId)); } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } } } diff --git a/Source/MQTTnet/Server/MqttServerClientDisconnectedEventArgs.cs b/Source/MQTTnet/Server/MqttServerClientDisconnectedEventArgs.cs index 9e74274..d2e7fe5 100644 --- a/Source/MQTTnet/Server/MqttServerClientDisconnectedEventArgs.cs +++ b/Source/MQTTnet/Server/MqttServerClientDisconnectedEventArgs.cs @@ -9,7 +9,11 @@ namespace MQTTnet.Server ClientId = clientId ?? throw new ArgumentNullException(nameof(clientId)); DisconnectType = disconnectType; } - + + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } public MqttClientDisconnectType DisconnectType { get; } diff --git a/Source/MQTTnet/Server/MqttServerClientSubscribedTopicEventArgs.cs b/Source/MQTTnet/Server/MqttServerClientSubscribedTopicEventArgs.cs index 94d6e26..3586b73 100644 --- a/Source/MQTTnet/Server/MqttServerClientSubscribedTopicEventArgs.cs +++ b/Source/MQTTnet/Server/MqttServerClientSubscribedTopicEventArgs.cs @@ -10,8 +10,16 @@ namespace MQTTnet.Server TopicFilter = topicFilter ?? throw new ArgumentNullException(nameof(topicFilter)); } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } + /// + /// Gets the topic filter. + /// The topic filter can contain topics and wildcards. + /// public MqttTopicFilter TopicFilter { get; } } } diff --git a/Source/MQTTnet/Server/MqttServerClientUnsubscribedTopicEventArgs.cs b/Source/MQTTnet/Server/MqttServerClientUnsubscribedTopicEventArgs.cs index bb78bb2..8ed1264 100644 --- a/Source/MQTTnet/Server/MqttServerClientUnsubscribedTopicEventArgs.cs +++ b/Source/MQTTnet/Server/MqttServerClientUnsubscribedTopicEventArgs.cs @@ -10,8 +10,16 @@ namespace MQTTnet.Server TopicFilter = topicFilter ?? throw new ArgumentNullException(nameof(topicFilter)); } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } + /// + /// Gets or sets the topic filter. + /// The topic filter can contain topics and wildcards. + /// public string TopicFilter { get; } } } diff --git a/Source/MQTTnet/Server/MqttServerOptions.cs b/Source/MQTTnet/Server/MqttServerOptions.cs index 31f56e5..ab52813 100644 --- a/Source/MQTTnet/Server/MqttServerOptions.cs +++ b/Source/MQTTnet/Server/MqttServerOptions.cs @@ -8,6 +8,10 @@ namespace MQTTnet.Server public MqttServerTlsTcpEndpointOptions TlsEndpointOptions { get; } = new MqttServerTlsTcpEndpointOptions(); + /// + /// Gets or sets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; set; } public bool EnablePersistentSessions { get; set; } diff --git a/Source/MQTTnet/Server/MqttSubscriptionInterceptorContext.cs b/Source/MQTTnet/Server/MqttSubscriptionInterceptorContext.cs index 0d800c8..cc186e5 100644 --- a/Source/MQTTnet/Server/MqttSubscriptionInterceptorContext.cs +++ b/Source/MQTTnet/Server/MqttSubscriptionInterceptorContext.cs @@ -11,8 +11,16 @@ namespace MQTTnet.Server SessionItems = sessionItems; } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } + /// + /// Gets or sets the topic filter. + /// The topic filter can contain topics and wildcards. + /// public MqttTopicFilter TopicFilter { get; set; } /// diff --git a/Source/MQTTnet/Server/MqttUnsubscriptionInterceptorContext.cs b/Source/MQTTnet/Server/MqttUnsubscriptionInterceptorContext.cs index b33cbac..e5f8d75 100644 --- a/Source/MQTTnet/Server/MqttUnsubscriptionInterceptorContext.cs +++ b/Source/MQTTnet/Server/MqttUnsubscriptionInterceptorContext.cs @@ -11,8 +11,17 @@ namespace MQTTnet.Server SessionItems = sessionItems; } + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; } + /// + /// Gets or sets the MQTT topic. + /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client. + /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). + /// public string Topic { get; set; } /// diff --git a/Source/MQTTnet/Server/Status/IMqttClientStatus.cs b/Source/MQTTnet/Server/Status/IMqttClientStatus.cs index d7debdc..c080b51 100644 --- a/Source/MQTTnet/Server/Status/IMqttClientStatus.cs +++ b/Source/MQTTnet/Server/Status/IMqttClientStatus.cs @@ -6,6 +6,10 @@ namespace MQTTnet.Server.Status { public interface IMqttClientStatus { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; } string Endpoint { get; } diff --git a/Source/MQTTnet/Server/Status/IMqttSessionStatus.cs b/Source/MQTTnet/Server/Status/IMqttSessionStatus.cs index 2ff996b..115da13 100644 --- a/Source/MQTTnet/Server/Status/IMqttSessionStatus.cs +++ b/Source/MQTTnet/Server/Status/IMqttSessionStatus.cs @@ -5,6 +5,10 @@ namespace MQTTnet.Server.Status { public interface IMqttSessionStatus { + /// + /// Gets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// string ClientId { get; } long PendingApplicationMessagesCount { get; } diff --git a/Source/MQTTnet/Server/Status/MqttClientStatus.cs b/Source/MQTTnet/Server/Status/MqttClientStatus.cs index 9acfea3..eca5d1a 100644 --- a/Source/MQTTnet/Server/Status/MqttClientStatus.cs +++ b/Source/MQTTnet/Server/Status/MqttClientStatus.cs @@ -14,6 +14,10 @@ namespace MQTTnet.Server.Status _connection = connection ?? throw new ArgumentNullException(nameof(connection)); } + /// + /// Gets or sets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; set; } public string Endpoint { get; set; } diff --git a/Source/MQTTnet/Server/Status/MqttSessionStatus.cs b/Source/MQTTnet/Server/Status/MqttSessionStatus.cs index a523a37..af5a6e8 100644 --- a/Source/MQTTnet/Server/Status/MqttSessionStatus.cs +++ b/Source/MQTTnet/Server/Status/MqttSessionStatus.cs @@ -15,6 +15,10 @@ namespace MQTTnet.Server.Status _sessionsManager = sessionsManager ?? throw new ArgumentNullException(nameof(sessionsManager)); } + /// + /// Gets or sets the client identifier. + /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues. + /// public string ClientId { get; set; } public long PendingApplicationMessagesCount { get; set; } From d804b805c14d85069fb2f6f2b83171def41d7352 Mon Sep 17 00:00:00 2001 From: SeppPenner Date: Fri, 15 Jan 2021 20:41:47 +0100 Subject: [PATCH 4/5] Smaller changes on the comments. --- .../IManagedMqttClient.cs | 8 ++++---- Source/MQTTnet/Client/IMqttClient.cs | 4 ---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs index 720ed12..9a76f09 100644 --- a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs +++ b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs @@ -19,11 +19,11 @@ namespace MQTTnet.Extensions.ManagedClient bool IsStarted { get; } bool IsConnected { get; } - + int PendingApplicationMessagesCount { get; } - + IManagedMqttClientOptions Options { get; } - + IMqttClientConnectedHandler ConnectedHandler { get; set; } IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } @@ -33,7 +33,7 @@ namespace MQTTnet.Extensions.ManagedClient IApplicationMessageSkippedHandler ApplicationMessageSkippedHandler { get; set; } IConnectingFailedHandler ConnectingFailedHandler { get; set; } - + ISynchronizingSubscriptionsFailedHandler SynchronizingSubscriptionsFailedHandler { get; set; } Task StartAsync(IManagedMqttClientOptions options); diff --git a/Source/MQTTnet/Client/IMqttClient.cs b/Source/MQTTnet/Client/IMqttClient.cs index dbe005a..394ec8d 100644 --- a/Source/MQTTnet/Client/IMqttClient.cs +++ b/Source/MQTTnet/Client/IMqttClient.cs @@ -14,10 +14,6 @@ namespace MQTTnet.Client { bool IsConnected { get; } - /// - /// Gets the options. - /// This contains all the set options for the client. - /// IMqttClientOptions Options { get; } /// From 3d8d06f9b3e15e872a5641058866844954001349 Mon Sep 17 00:00:00 2001 From: SeppPenner Date: Fri, 15 Jan 2021 20:43:57 +0100 Subject: [PATCH 5/5] Hopefully completely reset the IManagedMqttClient file. --- .../IManagedMqttClient.cs | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs index 9a76f09..cc2490c 100644 --- a/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs +++ b/Source/MQTTnet.Extensions.ManagedClient/IManagedMqttClient.cs @@ -17,33 +17,33 @@ namespace MQTTnet.Extensions.ManagedClient IMqttClient InternalClient { get; } bool IsStarted { get; } - + bool IsConnected { get; } - + int PendingApplicationMessagesCount { get; } - + IManagedMqttClientOptions Options { get; } - + IMqttClientConnectedHandler ConnectedHandler { get; set; } - + IMqttClientDisconnectedHandler DisconnectedHandler { get; set; } IApplicationMessageProcessedHandler ApplicationMessageProcessedHandler { get; set; } - + IApplicationMessageSkippedHandler ApplicationMessageSkippedHandler { get; set; } IConnectingFailedHandler ConnectingFailedHandler { get; set; } - + ISynchronizingSubscriptionsFailedHandler SynchronizingSubscriptionsFailedHandler { get; set; } Task StartAsync(IManagedMqttClientOptions options); - + Task StopAsync(); - + Task PingAsync(CancellationToken cancellationToken); Task SubscribeAsync(IEnumerable topicFilters); - + Task UnsubscribeAsync(IEnumerable topics); Task PublishAsync(ManagedMqttApplicationMessage applicationMessages);