Add mosquitto_subscribe_single()/multiple().

ChangeLog.txt

@@ -30,6 +30,9 @@ Client library:
 - Outgoing messages with QoS>1 are no longer retried after a timeout period.
   Messages will be retried when a client reconnects. 
 - DNS-SRV support is now disabled by default.
+- Add mosquitto_subscribe_single() and mosquitto_subscribe_multiple(). These
+  are two helper functions to make retrieving messages from a broker very
+  straightforward.
 
 Client:
 - Add -x to mosquitto_sub for printing the payload in hexadecimal format.

lib/Makefile

@@ -3,6 +3,7 @@ include ../config.mk
 .PHONY : really clean install
 
 MOSQ_OBJS=mosquitto.o \
+		  helpers.o \
 		  logging_mosq.o \
 		  memory_mosq.o \
 		  messages_mosq.o \
@@ -51,6 +52,9 @@ libmosquitto.a : ${MOSQ_OBJS}
 mosquitto.o : mosquitto.c mosquitto.h
 	${CROSS_COMPILE}$(CC) $(LIB_CFLAGS) -c $< -o $@
 
+helpers.o : helpers.c
+	${CROSS_COMPILE}$(CC) $(LIB_CFLAGS) -c $< -o $@
+
 logging_mosq.o : logging_mosq.c logging_mosq.h
 	${CROSS_COMPILE}$(CC) $(LIB_CFLAGS) -c $< -o $@
 

lib/linker.version

@@ -78,3 +78,9 @@ MOSQ_1.4 {
 		mosquitto_sub_topic_check;
 		mosquitto_socks5_set;
 } MOSQ_1.3;
+
+MOSQ_1.5 {
+	global:
+		mosquitto_subscribe_simple;
+		mosquitto_subscribe_multiple;
+} MOSQ_1.4;

lib/messages_mosq.c

@@ -66,7 +66,7 @@ int mosquitto_message_copy(struct mosquitto_message *dst, const struct mosquitto
 	dst->qos = src->qos;
 	dst->retain = src->retain;
 	if(src->payloadlen){
-		dst->payload = mosquitto__malloc(src->payloadlen);
+		dst->payload = mosquitto__calloc(src->payloadlen+1, sizeof(uint8_t));
 		if(!dst->payload){
 			mosquitto__free(dst->topic);
 			return MOSQ_ERR_NOMEM;
@@ -106,6 +106,14 @@ void mosquitto_message_free(struct mosquitto_message **message)
 	mosquitto__free(msg);
 }
 
+void mosquitto_message_free_contents(struct mosquitto_message *message)
+{
+	if(!message) return;
+
+	mosquitto__free(message->topic);
+	mosquitto__free(message->payload);
+}
+
 int message__queue(struct mosquitto *mosq, struct mosquitto_message_all *message, enum mosquitto_msg_direction dir)
 {
 	int rc = 0;

lib/mosquitto.h

@@ -672,10 +672,23 @@ libmosq_EXPORT int mosquitto_message_copy(struct mosquitto_message *dst, const s
  *	message - pointer to a mosquitto_message pointer to free.
  *
  * See Also:
- * 	<mosquitto_message_copy>
+ * 	<mosquitto_message_copy>, <mosquitto_message_free_contents>
  */
 libmosq_EXPORT void mosquitto_message_free(struct mosquitto_message **message);
 
+/*
+ * Function: mosquitto_message_free_contents
+ *
+ * Free a mosquitto_message struct contents, leaving the struct unaffected.
+ *
+ * Parameters:
+ *	message - pointer to a mosquitto_message struct to free its contents.
+ *
+ * See Also:
+ * 	<mosquitto_message_copy>, <mosquitto_message_free>
+ */
+libmosq_EXPORT void mosquitto_message_free_contents(struct mosquitto_message *message);
+
 /*
  * Function: mosquitto_loop
  *
@@ -1523,6 +1536,83 @@ libmosq_EXPORT int mosquitto_pub_topic_check(const char *topic);
  */
 libmosq_EXPORT int mosquitto_sub_topic_check(const char *topic);
 
+
+struct libmosquitto_will {
+	char *topic;
+	void *payload;
+	int payloadlen;
+	int qos;
+	bool retain;
+};
+
+struct libmosquitto_auth {
+	char *username;
+	char *password;
+};
+
+struct libmosquitto_tls {
+	char *cafile;
+	char *capath;
+	char *certfile;
+	char *keyfile;
+	char *ciphers;
+	char *tls_version;
+	int (*pw_callback)(char *buf, int size, int rwflag, void *userdata);
+	int cert_reqs;
+};
+
+/*
+ * Function: mosquitto_subscribe_simple
+ *
+ * Helper function to make subscribing to a topic and retrieving some messages
+ * very straightforward.
+ *
+ * This connects to a broker, subscribes to a topic, waits for msg_count
+ * messages to be received, then returns after disconnecting cleanly.
+ *
+ * Parameters:
+ *   messages - pointer to a "struct mosquitto_message *". The received
+ *              messages will be returned here. On error, this will be set to
+ *              NULL.
+ *   msg_count - the number of messages to retrieve.
+ *   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.
+ *   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
+ *               generated.
+ *   keepalive - the MQTT keepalive value.
+ *   clean_session - the MQTT clean session flag.
+ *   username - the username string, or NULL for no username authentication.
+ *   password - the password string, or NULL for an empty password.
+ *   will - a libmosquitto_will struct containing will information, or NULL for
+ *          no will.
+ *   tls - a libmosquitto_tls struct containing TLS related parameters, or NULL
+ *         for no use of TLS.
+ *
+ *
+ * Returns:
+ *   MOSQ_ERR_SUCCESS - on success
+ *   >0 - on error.
+ */
+libmosq_EXPORT int mosquitto_subscribe_simple(
+		struct mosquitto_message **messages,
+		int msg_count,
+		const char *topic,
+		int qos,
+		bool retained,
+		const char *host,
+		int port,
+		const char *client_id,
+		int keepalive,
+		bool clean_session,
+		const char *username,
+		const char *password,
+		const struct libmosquitto_will *will,
+		const struct libmosquitto_tls *tls);
 #ifdef __cplusplus
 }
 #endif

man/libmosquitto.3.xml

@@ -368,6 +368,27 @@
 					<paramdef>bool *<parameter>result</parameter></paramdef>
 			</funcprototype></funcsynopsis>
 		</refsect2>
+
+		<refsect2>
+			<title>Helper functions</title>
+
+			<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>const char *<parameter>topic</parameter></paramdef>
+					<paramdef>const char *<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>
+					<paramdef>int <parameter>keepalive</parameter></paramdef>
+					<paramdef>bool <parameter>clean_session</parameter></paramdef>
+					<paramdef>const char *<parameter>username</parameter></paramdef>
+					<paramdef>const char *<parameter>password</parameter></paramdef>
+					<paramdef>const struct libmosquitto_will *<parameter>will</parameter></paramdef>
+					<paramdef>const struct libmosquitto_tls *<parameter>tls</parameter></paramdef>
+			</funcprototype></funcsynopsis>
+		</refsect2>
 	</refsect1>
 
 	<refsect1>

src/bridge.c

@@ -180,7 +180,7 @@ int bridge__connect(struct mosquitto_db *db, struct mosquitto *context)
 	rc = net__socket_connect(context, context->bridge->addresses[context->bridge->cur_address].address, context->bridge->addresses[context->bridge->cur_address].port, NULL, false);
 	if(rc > 0 ){
 		if(rc == MOSQ_ERR_TLS){
-			_mosquitto_socket_close(db, context);
+			net__socket_close(db, context);
 			return rc; /* Error already printed */
 		}else if(rc == MOSQ_ERR_ERRNO){
 			log__printf(NULL, MOSQ_LOG_ERR, "Error creating bridge: %s.", strerror(errno));