TrueMQTT.h
10.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
/*
* Copyright (c) TrueBrain
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
#pragma once
#include <functional>
#include <memory>
namespace TrueMQTT
{
/**
* @brief MQTT Client class.
* This class manages the MQTT connection and provides methods to publish and subscribe to topics.
*/
class Client
{
public:
/**
* @brief Error codes that can be returned in the callback set by \ref setErrorCallback.
*/
enum Error
{
/**
* @brief The hostname could not be resolved into either an IPv4 or IPv6 address.
*
* This happens if the DNS server didn't return any valid IPv4 or IPv6 address
* based on the hostname given.
*
* Due to the nature of this error, this library has no way to recover from
* this. As such, this is considered a fatal error and the library takes no
* attempt to gracefully handle this.
*
* @note This is a fatal error. You have to call \ref disconnect after this.
*/
HOSTNAME_LOOKUP_FAILED,
/**
* @brief The subscription failed.
*
* The topic that failed to subscribe is passed as the second argument.
*
* @note This error is non-fatal.
*/
SUBSCRIBE_FAILED,
/**
* @brief The unsubscription failed.
*
* The topic that failed to unsubscribe is passed as the second argument.
*
* @note This error is non-fatal.
*/
UNSUBSCRIBE_FAILED,
};
/**
* @brief The type of queue that can be set for publishing messages.
*
* When there is no connection to a broker, some choices have to be made what
* to do with messages that are published.
*
* - Do we queue the message?
* - What do we do when the queue is full?
*
* After all, memory is finite, so this allows you to configure what scenario
* works best for you.
*/
enum PublishQueueType
{
DROP, ///< Do not queue.
/**
* @brief First-in-First-out queue.
*
* For a size 3 queue this means if we publish 6 messages (M1 .. M6), the result is:
*
* [ M4, M5, M6 ]
*
* When publishing the next message (M7) it becomes:
*
* [ M5, M6, M7 ]
*/
FIFO,
/**
* @brief Last-in-First-out queue.
*
* For a size 3 queue this means if we publish 6 messages (M1 .. M6), the result is:
*
* [ M1, M2, M6 ]
*
* When publishing the next message (M7) it becomes:
*
* [ M1, M2, M7 ]
*/
LIFO,
};
/**
* @brief The log levels used by this library.
*/
enum LogLevel
{
NONE, ///< Do not log anything (default).
ERROR, ///< Something went wrong and the library cannot recover.
WARNING, ///< Something wasn't right, but the library can recover.
INFO, ///< Information that might be useful to know.
DEBUG, ///< Information that might be useful for debugging.
TRACE, ///< Information that is overly verbose to tell exactly what the library is doing.
};
/**
* @brief Constructor for the MQTT client.
*
* @param host The hostname of the MQTT broker. Can be either an IP or a domain name.
* @param port Port of the MQTT broker.
* @param client_id Client ID to use when connecting to the broker.
* @param connection_timeout Timeout in seconds for the connection to the broker.
* @param connection_backoff_max Maximum time between backoff attempts in seconds.
* @param keep_alive_interval Interval in seconds between keep-alive messages.
*/
Client(const std::string &host, int port, const std::string &client_id, int connection_timeout = 5, int connection_backoff_max = 30, int keep_alive_interval = 30);
/**
* @brief Destructor of the MQTT client.
*
* Before destruction, any open connection is closed gracefully.
*/
~Client();
/**
* @brief Set the logger callback and level.
*
* @param log_level The \ref LogLevel to use for logging.
* @param logger The callback to call when a log message is generated.
*
* @note This library doesn't contain a logger, so you need to provide one.
* If this method is not called, no logging will be done.
*/
void setLogger(LogLevel log_level, std::function<void(LogLevel, std::string)> logger);
/**
* @brief Set the last will message on the connection.
*
* @param topic The topic to publish the last will message to.
* @param payload The payload of the last will message.
* @param retain Whether to retain the last will message.
*
* @note Cannot be called after \ref connect.
*/
void setLastWill(const std::string &topic, const std::string &payload, bool retain);
/**
* @brief Set the error callback, called when any error occurs.
*
* @param callback The callback to call when an error occurs.
*/
void setErrorCallback(std::function<void(Error, std::string)> callback);
/**
* @brief Set the publish queue to use.
*
* @param queue_type The \ref PublishQueueType to use for the publish queue.
* @param size The size of the queue. If the queue is full, the type of queue defines what happens.
*
* @note Cannot be called after \ref connect.
*/
void setPublishQueue(PublishQueueType queue_type, size_t size);
/**
* @brief Connect to the broker.
*
* After calling this function, the library will try a connection to the broker.
* If the connection fails, it will try again after a backoff period.
* The backoff period will increase until it reaches the maximum backoff period.
*
* If the connection succeeds, but it disconnected later (without calling \ref disconnect),
* the library will try to reconnect.
*
* @note Calling connect twice has no effect.
*/
void connect();
/**
* @brief Disconnect from the broker.
*
* This function will disconnect from the broker and stop trying to reconnect.
* Additionally, it will clean any publish / subscribe information it has.
*
* @note Calling disconnect twice has no effect.
* @note This function can stall for a short moment if you disconnect just at the
* moment the connection to the broker is established, and there are messages in the
* publish queue and/or subscriptions.
*/
void disconnect();
/**
* @brief Publish a payload on a topic.
*
* After \ref connect is called, this function will either publish the message
* immediately (if connected) or queue it for later (if still connecting).
* In the latter case, it will be published as soon as the connection is established.
*
* @param topic The topic to publish the payload on.
* @param payload The payload to publish.
* @param retain Whether to retain the message on the broker.
*
* @note All messages are always published under QoS 0, and this library supports no
* other QoS level.
* @note This call is non-blocking, and it is not possible to know whether the message
* was actually published or not.
* @note You cannot publish a message if you are disconnected from the broker. Call
* \ref connect first.
* @note This function can stall for a short moment if you publish just at the
* moment the connection to the broker is established, and there are messages in the
* publish queue and/or subscriptions.
*/
void publish(const std::string &topic, const std::string &payload, bool retain);
/**
* @brief Subscribe to a topic, and call the callback function when a message arrives.
*
* After \ref connect is called, this function will either subscribe to the topic
* immediately (if connected) or subscribe to it once a connection has been made.
* In case of a reconnect, it will also automatically resubscribe.
*
* If the broker refuses the subscribe request, the error-callback is called.
*
* @param topic The topic to subscribe to.
* @param callback The callback to call when a message arrives on this topic.
*
* @note Subscription can overlap, but you cannot subscribe on the exact same topic twice.
* If you do, the callback of the first subscription will be overwritten.
* In other words, "a/+" and "a/b" is fine, and callbacks for both subscribes will be
* called when something is published on "a/b".
* @note You cannot subscribe a topic if you are disconnected from the broker. Call
* \ref connect first.
* @note This function can stall for a short moment if you publish just at the
* moment the connection to the broker is established, and there are messages in the
* publish queue and/or subscriptions.
*/
void subscribe(const std::string &topic, std::function<void(std::string, std::string)> callback);
/**
* @brief Unsubscribe from a topic.
*
* If the broker refuses the unsubscribe request, the error-callback is called.
*
* @param topic The topic to unsubscribe from.
*
* @note If you unsubscribe from a topic you were not subscribed too, nothing happens.
* @note You cannot unsubscribe from a topic if you are disconnected from the broker.
* Call \ref connect (and \ref subscribe) first.
* @note This function can stall for a short moment if you publish just at the
* moment the connection to the broker is established, and there are messages in the
* publish queue and/or subscriptions.
*/
void unsubscribe(const std::string &topic);
private:
// Private implementation
class Impl;
std::unique_ptr<Impl> m_impl;
};
}