eclipse/paho.mqtt.cpp
1
0
Fork 0
mirror of https://github.com/eclipse/paho.mqtt.cpp.git synced 2025-05-09 03:11:23 +08:00
Code Issues Releases Wiki Activity

Fixed doc comment and deprecation warnings.

Browse Source
This commit is contained in:
fpagliughi 2024-06-26 21:45:20 -04:00
parent 381caad141
commit 91bfc64bdd
19 changed files with 92 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
examples/async_publish_time.cpp
View File

@ -130,8 +130,7 @@ int main(int argc, char* argv[])
auto top = mqtt::topic(cli, "data/time", QOS);
cout << "Publishing data..." << endl;
while (timestamp() % DELTA_MS != 0)
;
while (timestamp() % DELTA_MS != 0);
uint64_t t = timestamp(), tlast = t, tstart = t;

3
examples/async_subscribe.cpp
View File

@ -205,8 +205,7 @@ int main(int argc, char* argv[])
// Just block till user tells us to quit.
while (std::tolower(std::cin.get()) != 'q')
;
while (std::tolower(std::cin.get()) != 'q');
// Disconnect

3
examples/sync_consume_v5.cpp
View File

@ -84,8 +84,7 @@ int main(int argc, char* argv[])
{
mqtt::client cli(SERVER_ADDRESS, CLIENT_ID, mqtt::create_options(MQTTVERSION_5));
auto connOpts = mqtt::connect_options_builder()
.mqtt_version(MQTTVERSION_5)
auto connOpts = mqtt::connect_options_builder::v5()
.automatic_reconnect(seconds(2), seconds(30))
.clean_start(false)
.properties({{mqtt::property::SESSION_EXPIRY_INTERVAL, INFINITE}})

34
include/mqtt/async_client.h
View File

@ -196,7 +196,6 @@ private:
* server, which allows for off-line message buffering.
* This allows the caller to specify a user-defined persistence object,
* or use no persistence.
* @param opts The create options
* @throw exception if an argument is invalid
*/
void create();
@ -223,8 +222,7 @@ public:
* as a URI.
* @param clientId a client identifier that is unique on the server
* being connected to
* @param persistence The user persistence structure. If this is null,
* then no persistence is used.
* @param persistence The persistence that the client should use.
* @throw exception if an argument is invalid
*/
async_client(
@ -243,7 +241,7 @@ public:
* being connected to
* @param maxBufferedMessages the maximum number of messages allowed to
* be buffered while not connected
* @param persistDir The directory to use for persistence data
* @param persistence The persistence that the client should use.
* @throw exception if an argument is invalid
*/
async_client(
@ -262,7 +260,7 @@ public:
* @param clientId a client identifier that is unique on the server
* being connected to
* @param opts The create options
* @param persistDir The directory to use for persistence data
* @param persistence The persistence that the client should use.
* @throw exception if an argument is invalid
*/
async_client(
@ -582,7 +580,7 @@ public:
* server.
* @param userContext optional object used to pass context to the
* callback. Use @em nullptr if not required.
* @param cb
* @param cb Listener callback object
* @return token used to track and wait for the publish to complete. The
* token will be passed to callback methods if set.
*/
@ -631,7 +629,7 @@ public:
* Subscribe to a topic, which may include wildcards.
* @param topicFilter the topic to subscribe to, which can include
* wildcards.
* @param qos the maximum quality of service at which to subscribe.
* @param qos The maximum quality of service at which to subscribe.
* Messages published at a lower quality of service will be
* received at the published QoS. Messages published at a
* higher quality of service will be received using the QoS
@ -651,8 +649,9 @@ public:
) override;
/**
* Subscribe to multiple topics, each of which may include wildcards.
* @param topicFilters
* @param qos the maximum quality of service at which to subscribe.
* @param topicFilters The collection of topic filters to subscribe to,
* any of which can include wildcards
* @param qos The maximum quality of service at which to subscribe.
* Messages published at a lower quality of service will be
* received at the published QoS. Messages published at a
* higher quality of service will be received using the QoS
@ -669,13 +668,14 @@ public:
) override;
/**
* Subscribes to multiple topics, each of which may include wildcards.
* @param topicFilters
* @param qos the maximum quality of service at which to subscribe.
* @param topicFilters The collection of topic filters to subscribe to,
* any of which can include wildcards
* @param qos The maximum quality of service at which to subscribe.
* Messages published at a lower quality of service will be
* received at the published QoS. Messages published at a
* higher quality of service will be received using the QoS
* specified on the subscribe.
* @param userContext optional object used to pass context to the
* @param userContext Optional object used to pass context to the
* callback. Use @em nullptr if not required.
* @param cb listener that will be notified when subscribe has completed
* @param opts The MQTT v5 subscribe options (one for each topic)
@ -691,17 +691,17 @@ public:
) override;
/**
* Requests the server unsubscribe the client from a topic.
* @param topicFilter the topic to unsubscribe from. It must match a
* @param topicFilter The topic to unsubscribe from. It must match a
* topicFilter specified on an earlier subscribe.
* @param props The MQTT v5 properties.
* @return token used to track and wait for the unsubscribe to complete.
* @return token Used to track and wait for the unsubscribe to complete.
* The token will be passed to callback methods if set.
*/
token_ptr unsubscribe(const string& topicFilter, const properties& props = properties())
override;
/**
* Requests the server unsubscribe the client from one or more topics.
* @param topicFilters one or more topics to unsubscribe from. Each
* @param topicFilters One or more topics to unsubscribe from. Each
* topicFilter must match one specified on an
* earlier subscribe.
* @param props The MQTT v5 properties.
@ -713,7 +713,9 @@ public:
) override;
/**
* Requests the server unsubscribe the client from one or more topics.
* @param topicFilters
* @param topicFilters One or more topics to unsubscribe from. Each
* topicFilter must match one specified on an
* earlier subscribe.
* @param userContext optional object used to pass context to the
* callback. Use @em nullptr if not required.
* @param cb listener that will be notified when unsubscribe has

6
include/mqtt/client.h
View File

@ -184,7 +184,7 @@ public:
virtual connect_response connect();
/**
* Connects to an MQTT server using the specified options.
* @param opts
* @param opts The connect options
*/
virtual connect_response connect(connect_options opts);
/**
@ -327,8 +327,8 @@ public:
}
/**
* Subscribe to a topic, which may include wildcards using a QoS of 1.
* @param topicFilter
* @param props The MQTT v5 properties.
* @param topicFilter A single topic to subscribe
maked * @param props The MQTT v5 properties.
* @param opts The MQTT v5 subscribe options for the topic
* @return The "subscribe" response from the server.
*/

29
include/mqtt/connect_options.h
View File

@ -106,7 +106,7 @@ class connect_options
* @note In the connect options, by default, the Paho C treats
* nullptr char arrays as unset values, so we keep that semantic and
* only set those char arrays if the string is non-empty.
* @param str The C++ string object.
* @param sr The C++ string object.
* @return Pointer to a NUL terminated string. This is only valid until
* the next time the string is updated.
*/
@ -295,8 +295,8 @@ public:
*/
const_string_collection_ptr get_servers() const { return serverURIs_; }
/**
* Gets the version of MQTT to be used on the connect.
* @return
* Gets the version of MQTT to be used for the connection.
* @return The version of MQTT to be used for the connection:
* @li MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that
* fails, fall back to 3.1
* @li MQTTVERSION_3_1 (3) = only try version 3.1
@ -333,8 +333,8 @@ public:
* This will only take effect if the version is _already_ set to v3.x
* (not v5).
*
* @param clean @em true if the server should NOT remember state for the
* client across reconnects, @em false otherwise.
* @param cleanSession @em true if the server should NOT remember state
* for the client across reconnects, @em false otherwise.
*/
void set_clean_session(bool cleanSession);
/**
@ -347,8 +347,8 @@ public:
*
* This will only take effect if the MQTT version is set to v5
*
* @param clean @em true if the server should NOT remember state for the
* client across reconnects, @em false otherwise.
* @param cleanStart @em true if the server should NOT remember state
* for the client across reconnects, @em false otherwise.
*/
void set_clean_start(bool cleanStart);
/**
@ -463,7 +463,9 @@ public:
* call it before setting any other version-specific options. @sa
* connect_options::v5()
*/
void set_mqtt_version(int mqttVersion);
[[deprecated("Use a versioned creation function to construct for the desired version"
)]] void
set_mqtt_version(int mqttVersion);
/**
* Enable or disable automatic reconnects.
* The retry intervals are not affected.
@ -747,15 +749,16 @@ public:
return *this;
}
/**
* Sets the user name to use for the connection.
* @param userName
* Sets the user name for the connection.
* @param userName The user name for the connection.
*/
auto user_name(string_ref userName) -> self& {
opts_.set_user_name(userName);
return *this;
}
/**
* Sets the password to use for the connection.
* Sets the password for the connection.
* @param password The password for the connection.
*/
auto password(binary_ref password) -> self& {
opts_.set_password(password);
@ -853,7 +856,9 @@ public:
* this function, call it before setting any other version-specific
* options. @sa connect_options_builder::v5()
*/
auto mqtt_version(int ver) -> self& {
[[deprecated("Use a versioned creation function to construct for the desired version"
)]] auto
mqtt_version(int ver) -> self& {
opts_.set_mqtt_version(ver);
return *this;
}

6
include/mqtt/create_options.h
View File

@ -136,7 +136,7 @@ public:
* being connected to
* @param maxBufferedMessages the maximum number of messages allowed to
* be buffered while not connected
* @param persistDir The directory to use for persistence data
* @param persistence The persistence that the client should use.
* @throw exception if an argument is invalid
*/
create_options(
@ -155,7 +155,7 @@ public:
* @param clientId a client identifier that is unique on the server
* being connected to
* @param opts The create options
* @param persistDir The directory to use for persistence data
* @param persistence The persistence that the client should use.
* @throw exception if an argument is invalid
*/
create_options(
@ -199,7 +199,7 @@ public:
const string& get_server_uri() const noexcept { return serverURI_; };
/**
* Set the client identifier.
* @param The client identifier.
* @param clientId The client identifier.
*/
void set_client_id(const string& clientId) { clientId_ = clientId; }
/**

2
include/mqtt/delivery_token.h
View File

@ -49,7 +49,7 @@ class delivery_token : public token
/**
* Sets the message to which this token corresponds.
* @param msg
* @param msg The message to which this token corresponds.
*/
void set_message(const_message_ptr msg) { msg_ = msg; }

4
include/mqtt/iaction_listener.h
View File

@ -60,12 +60,12 @@ public:
virtual ~iaction_listener() {}
/**
* This method is invoked when an action fails.
* @param asyncActionToken
* @param asyncActionToken The token
*/
virtual void on_failure(const token& asyncActionToken) = 0;
/**
* This method is invoked when an action has completed successfully.
* @param asyncActionToken
* @param asyncActionToken The token
*/
virtual void on_success(const token& asyncActionToken) = 0;
};

18
include/mqtt/iasync_client.h
View File

@ -196,11 +196,11 @@ public:
/**
* Publishes a message to a topic on the server
* @param topic The topic to deliver the message to
* @param payload the bytes to use as the message payload
* @param n the number of bytes in the payload
* @param qos the Quality of Service to deliver the message at. Valid
* @param payload The bytes to use as the message payload
* @param n The number of bytes in the payload
* @param qos The Quality of Service to deliver the message at. Valid
* values are 0, 1 or 2.
* @param retained whether or not this message should be retained by the
* @param retained Whether or not this message should be retained by the
* server.
* @return token used to track and wait for the publish to complete. The
* token will be passed to callback methods if set.
@ -220,15 +220,15 @@ public:
/**
* Publishes a message to a topic on the server
* @param topic The topic to deliver the message to
* @param payload the bytes to use as the message payload
* @param n the number of bytes in the payload
* @param qos the Quality of Service to deliver the message at. Valid
* @param payload The bytes to use as the message payload
* @param n The number of bytes in the payload
* @param qos The Quality of Service to deliver the message at. Valid
* values are 0, 1 or 2.
* @param retained whether or not this message should be retained by the
* server.
* @param userContext optional object used to pass context to the
* @param userContext Optional object used to pass context to the
* callback. Use @em nullptr if not required.
* @param cb
* @param cb The listener callback object
* @return token used to track and wait for the publish to complete. The
* token will be passed to callback methods if set.
*/

2
include/mqtt/message.h
View File

@ -79,7 +79,7 @@ private:
/**
* Set the dup flag in the underlying message
* @param dup
* @param dup Whether to set the dup flag.
*/
void set_duplicate(bool dup) { msg_.dup = to_int(dup); }

6
include/mqtt/properties.h
View File

@ -224,7 +224,8 @@ inline uint16_t get<uint16_t>(const property& prop) {
* `get<uint16_t>()`
*/
template <>
inline int16_t get<int16_t>(const property& prop) {
[[deprecated("Integer properties are unsigned. Use get<uint16_t>()")]] inline int16_t
get<int16_t>(const property& prop) {
return (int16_t)prop.c_struct().value.integer2;
}
@ -244,7 +245,8 @@ inline uint32_t get<uint32_t>(const property& prop) {
* `get<uint32_t>()`
*/
template <>
inline int32_t get<int32_t>(const property& prop) {
[[deprecated("Integer properties are unsigned. Use get<uint32_t>()")]] inline int32_t
get<int32_t>(const property& prop) {
return (int32_t)prop.c_struct().value.integer4;
}

4
include/mqtt/thread_queue.h
View File

@ -61,8 +61,8 @@ namespace mqtt {
* shared pointers, as the "dead" part of the queue will not hold onto a
* reference count after the item has been removed from the queue.
*
* @param T The type of the items to be held in the queue.
* @param Container The type of the underlying container to use. It must
* @tparam T The type of the items to be held in the queue.
* @tparam Container The type of the underlying container to use. It must
* support back(), front(), push_back(), pop_front().
*/
template <typename T, class Container = std::deque<T>>

8
include/mqtt/topic.h
View File

@ -6,7 +6,7 @@
/////////////////////////////////////////////////////////////////////////////
/*******************************************************************************
* Copyright (c) 2013-2016 Frank Pagliughi <fpagliughi@mindspring.com>
* Copyright (c) 2013-2024 Frank Pagliughi <fpagliughi@mindspring.com>
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v2.0
@ -212,13 +212,13 @@ public:
*/
explicit topic_filter(const string& filter);
/**
* Determines if the specified topic filter contains any wildcards.
* Determines if the specified topic/filter contains any wildcards.
*
* @param filter The topic filter string to check for wildcards.
* @param filter The topic/filter string to check for wildcards.
* @return @em true if any of the fields contain a wildcard, @em false
* if not.
*/
static bool has_wildcards(const string& topic);
static bool has_wildcards(const string& filter);
/**
* Determines if this topic filter contains any wildcards.
*

2
include/mqtt/will_options.h
View File

@ -86,7 +86,7 @@ private:
* while others expect NULL pointers for missing parameters.
* So we always return a pointer to a valid C char array, even when
* empty.
* @param str The C++ string object.
* @param sr The C++ string object.
* @return Pointer to a NUL terminated string. This is only valid until
* the next time the string is updated. This is never nullptr.
*/

2
src/properties.cpp
View File

@ -202,7 +202,7 @@ std::ostream& operator<<(std::ostream& os, const property& prop)
case MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER:
case MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER:
case MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER:
os << get<int>(prop);
os << get<uint32_t>(prop);
break;
case MQTTPROPERTY_TYPE_BINARY_DATA: {

20
test/unit/test_connect_options.cpp
View File

@ -255,7 +255,9 @@ TEST_CASE("connect_options move_constructor", "[options]")
// Check that we got the correct properties
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
}
@ -317,7 +319,9 @@ TEST_CASE("connect_options copy_assignment", "[options]")
// Check that we got the correct properties
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
}
@ -381,7 +385,9 @@ TEST_CASE("connect_options move_assignment", "[options]")
// Check that we got the correct properties
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
}
@ -682,7 +688,9 @@ TEST_CASE("connect_options_builder copy_assignment", "[options]")
// Check that we got the correct properties
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
}
}
@ -739,6 +747,8 @@ TEST_CASE("connect_options_builder move_assignment", "[options]")
// Check that we got the correct properties
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
}
}

4
test/unit/test_disconnect_options.cpp
View File

@ -116,7 +116,9 @@ TEST_CASE("disconnect_options copy ctor", "[options]")
// Check that the properties transferred over
REQUIRE(1 == opts.get_properties().size());
REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
REQUIRE(
42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
);
REQUIRE(1 == opts.c_struct().properties.count);
REQUIRE(

10
test/unit/test_properties.cpp
View File

@ -78,7 +78,7 @@ TEST_CASE("int property constructor", "[property]")
REQUIRE(prop.c_struct().value.integer2 == 512);
REQUIRE(prop.type() == typ);
REQUIRE(get<int16_t>(prop) == int16_t(512));
REQUIRE(get<uint16_t>(prop) == 512);
// Should be able to support full 16-bit unsigned range
const uint16_t MAX = std::numeric_limits<uint16_t>::max();
@ -103,7 +103,7 @@ TEST_CASE("int property constructor", "[property]")
REQUIRE(prop.c_struct().value.integer4 == 70000);
REQUIRE(prop.type() == typ);
REQUIRE(get<int32_t>(prop) == int32_t(70000));
REQUIRE(get<uint32_t>(prop) == 70000);
// Should be able to support full 32-bit unsigned range
const uint32_t MAX = std::numeric_limits<uint32_t>::max();
@ -235,7 +235,7 @@ TEST_CASE("int property copy constructor", "[property]")
REQUIRE(prop.c_struct().value.integer4 == 70000);
REQUIRE(prop.type() == typ);
REQUIRE(get<int32_t>(prop) == int32_t(70000));
REQUIRE(get<uint32_t>(prop) == 70000);
}
}
@ -252,7 +252,7 @@ TEST_CASE("int property move constructor", "[property]")
REQUIRE(prop.c_struct().value.integer4 == 70000);
REQUIRE(prop.type() == typ);
REQUIRE(get<int32_t>(prop) == int32_t(70000));
REQUIRE(get<uint32_t>(prop) == 70000);
// Make sure the old value was moved
REQUIRE(org_prop.c_struct().identifier == 0);
@ -434,7 +434,7 @@ TEST_CASE("properties constructors", "[properties]")
REQUIRE(props.size() == 2);
REQUIRE(42 == get<uint8_t>(props, property::PAYLOAD_FORMAT_INDICATOR));
REQUIRE(70000 == get<int>(props, property::MESSAGE_EXPIRY_INTERVAL));
REQUIRE(70000 == get<uint32_t>(props, property::MESSAGE_EXPIRY_INTERVAL));
}
}