Reorder helper function arguments for consistency.

ChangeLog.txt

@@ -31,8 +31,11 @@ Client library:
  Messages will be retried when a client reconnects. 
 - DNS-SRV support is now disabled by default.
 - Add mosquitto_subscribe_simple() This is a helper function to make
- retrieving messages from a broker very straightforward. Examples of its user
+ retrieving messages from a broker very straightforward. Examples of its use
  are in examples/subscribe_simple.
+- Add mosquitto_subscribe_callback() This is a helper function to make
+ processing messages from a broker very straightforward. An example of its use
+ is in examples/subscribe_simple.
 
 Client:
 - Add -x to mosquitto_sub for printing the payload in hexadecimal format.

examples/subscribe_simple/callback.c

@@ -16,8 +16,8 @@ int main(int argc, char *argv[])
  mosquitto_lib_init();
 
  rc = mosquitto_subscribe_callback(
- on_message,
- "irc/#", 0, NULL,
+ on_message, NULL,
+ "irc/#", 0,
  "test.mosquitto.org", 1883,
  NULL, 60, true,
  NULL, NULL,

examples/subscribe_simple/multiple.c

@@ -13,8 +13,8 @@ int main(int argc, char *argv[])
  mosquitto_lib_init();
 
  rc = mosquitto_subscribe_simple(
- &msg, COUNT,
- "irc/#", 0, true,
+ &msg, COUNT, true,
+ "irc/#", 0,
  "test.mosquitto.org", 1883,
  NULL, 60, true,
  NULL, NULL,

examples/subscribe_simple/single.c

@@ -10,8 +10,8 @@ int main(int argc, char *argv[])
  mosquitto_lib_init();
 
  rc = mosquitto_subscribe_simple(
- &msg, 1,
- "irc/#", 0, true,
+ &msg, 1, true,
+ "irc/#", 0,
  "test.mosquitto.org", 1883,
  NULL, 60, true,
  NULL, NULL,

lib/cpp/mosquittopp.cpp

@@ -109,9 +109,9 @@ int topic_matches_sub(const char *sub, const char *topic, bool *result)
 int subscribe_simple(
  struct mosquitto_message **messages,
  int msg_count,
+ bool retained,
  const char *topic,
  int qos,
- bool retained,
  const char *host,
  int port,
  const char *client_id,
@@ -122,18 +122,19 @@ int subscribe_simple(
  const struct libmosquitto_will *will,
  const struct libmosquitto_tls *tls)
 {
- return mosquitto_subscribe_simple(messages, msg_count, topic, qos, retained,
+ return mosquitto_subscribe_simple(
+ messages, msg_count, retained,
+ topic, qos,
  host, port, client_id, keepalive, clean_session,
  username, password,
  will, tls);
 }
 
 mosqpp_EXPORT int subscribe_callback(
  int (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),
+ void *userdata,
  const char *topic,
  int qos,
- void *userdata,
- bool retained,
  const char *host,
  int port,
  const char *client_id,
@@ -144,7 +145,9 @@ mosqpp_EXPORT int subscribe_callback(
  const struct libmosquitto_will *will,
  const struct libmosquitto_tls *tls)
 {
- return mosquitto_subscribe_callback(callback, topic, qos, userdata, retained,
+ return mosquitto_subscribe_callback(
+ callback, userdata,
+ topic, qos,
  host, port, client_id, keepalive, clean_session,
  username, password,
  will, tls);

lib/cpp/mosquittopp.h

@@ -44,9 +44,9 @@ mosqpp_EXPORT int topic_matches_sub(const char *sub, const char *topic, bool *re
 mosqpp_EXPORT int subscribe_simple(
  struct mosquitto_message **messages,
  int msg_count,
+ bool retained,
  const char *topic,
  int qos=0,
- bool retained=true,
  const char *host="localhost",
  int port=1883,
  const char *client_id=NULL,
@@ -59,9 +59,9 @@ mosqpp_EXPORT int subscribe_simple(
 
 mosqpp_EXPORT int subscribe_callback(
  int (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),
+ void *userdata,
  const char *topic,
  int qos=0,
- void *userdata=NULL,
  bool retained=true,
  const char *host="localhost",
  int port=1883,

lib/helpers.c

@@ -86,9 +86,9 @@ static int on_message_simple(struct mosquitto *mosq, void *obj, const struct mos
 libmosq_EXPORT int mosquitto_subscribe_simple(
  struct mosquitto_message **messages,
  int msg_count,
+ bool retained,
  const char *topic,
  int qos,
- bool retained,
  const char *host,
  int port,
  const char *client_id,
@@ -117,9 +117,9 @@ libmosq_EXPORT int mosquitto_subscribe_simple(
  userdata.max_msg_count = msg_count;
  userdata.retained = retained;
 
- rc = mosquitto_subscribe_callback(on_message_simple,
+ rc = mosquitto_subscribe_callback(
+ on_message_simple, &userdata,
  topic, qos,
- &userdata,
  host, port,
  client_id, keepalive, clean_session,
  username, password,
@@ -138,11 +138,12 @@ libmosq_EXPORT int mosquitto_subscribe_simple(
  }
 }
 
+
 libmosq_EXPORT int mosquitto_subscribe_callback(
  int (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),
+ void *userdata,
  const char *topic,
  int qos,
- void *userdata,
  const char *host,
  int port,
  const char *client_id,

lib/mosquitto.h

@@ -1575,9 +1575,9 @@ struct libmosquitto_tls {
  * messages will be returned here. On error, this will be set to
  * NULL.
  * msg_count - the number of messages to retrieve.
+ * retained - if set to true, stale retained messages will be treated as
  * topic - the subscription topic to use (wildcards are allowed).
  * qos - the qos to use for the subscription.
- * retained - if set to true, stale retained messages will be treated as
  * normal messages with regards to msg_count. If set to false,
  * they will be ignored.
  * host - the broker to connect to.
@@ -1601,9 +1601,9 @@ struct libmosquitto_tls {
 libmosq_EXPORT int mosquitto_subscribe_simple(
  struct mosquitto_message **messages,
  int msg_count,
+ bool retained,
  const char *topic,
  int qos,
- bool retained,
  const char *host,
  int port,
  const char *client_id,
@@ -1630,9 +1630,9 @@ libmosq_EXPORT int mosquitto_subscribe_simple(
  * int callback(struct mosquitto *mosq, void *obj, const struct mosquitto_message *message)
  * Note that this is the same as the normal on_message callback,
  * except that it returns an int.
+ * userdata - user provided pointer that will be passed to the callback.
  * topic - the subscription topic to use (wildcards are allowed).
  * qos - the qos to use for the subscription.
- * userdata - user provided pointer that will be passed to the callback.
  * host - the broker to connect to.
  * port - the network port the broker is listening on.
  * client_id - the client id to use, or NULL if a random client id should be
@@ -1653,9 +1653,9 @@ libmosq_EXPORT int mosquitto_subscribe_simple(
  */
 libmosq_EXPORT int mosquitto_subscribe_callback(
  int (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),
+ void *userdata,
  const char *topic,
  int qos,
- void *userdata,
  const char *host,
  int port,
  const char *client_id,

man/libmosquitto.3.xml

@@ -375,9 +375,9 @@
  <funcsynopsis><funcprototype><funcdef>int <function>mosquitto_subscribe_simple</function></funcdef>
  <paramdef>struct mosquitto_message **<parameter>message</parameter></paramdef>
  <paramdef>int <parameter>msg_count</parameter></paramdef>
+ <paramdef>bool <parameter>retained</parameter></paramdef>
  <paramdef>const char *<parameter>topic</parameter></paramdef>
  <paramdef>int<parameter>qos</parameter></paramdef>
- <paramdef>bool <parameter>retained</parameter></paramdef>
  <paramdef>const char *<parameter>host</parameter></paramdef>
  <paramdef>int <parameter>port</parameter></paramdef>
  <paramdef>const char *<parameter>client_id</parameter></paramdef>
@@ -391,9 +391,9 @@
 
  <funcsynopsis><funcprototype><funcdef>int <function>mosquitto_subscribe_callback</function></funcdef>
  <paramdef>int <parameter>(*callback)(struct mosquitto *, void *, const struct mosquitto_message *)</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
  <paramdef>const char *<parameter>topic</parameter></paramdef>
  <paramdef>int <parameter>qos</parameter></paramdef>
- <paramdef>void *<parameter>userdata</parameter></paramdef>
  <paramdef>const char *<parameter>host</parameter></paramdef>
  <paramdef>int <parameter>port</parameter></paramdef>
  <paramdef>const char *<parameter>client_id</parameter></paramdef>