Add --remove-retained to mosquitto_sub

This can be used to clear retained messages on a broker.

ChangeLog.txt

@@ -28,6 +28,8 @@ Client features:
 - Add -E to mosquitto_sub, which causes it to exit immediately after having
   its subscriptions acknowledged. Use with -c to create a durable client
   session without requiring a message to be received.
+- Add --remove-retained to mosquitto_sub, which can be used to clear retained
+  messages on a broker.
 - -V now accepts `5, `311`, `31`, as well as `mqttv5` etc.
 - Add TLS Engine support.
 - Add explicit support for TLS v1.3.

client/client_shared.c

@@ -803,6 +803,11 @@ int client_config_line_proc(struct mosq_config *cfg, int pub_or_sub, int argc, c
 			i++;
 		}else if(!strcmp(argv[i], "--quiet")){
 			cfg->quiet = true;
+		}else if(!strcmp(argv[i], "--remove-retained")){
+			if(pub_or_sub == CLIENT_PUB){
+				goto unknown_option;
+			}
+			cfg->remove_retained = true;
 		}else if(!strcmp(argv[i], "-r") || !strcmp(argv[i], "--retain")){
 			if(pub_or_sub == CLIENT_SUB){
 				goto unknown_option;

client/client_shared.h

@@ -80,6 +80,7 @@ struct mosq_config {
 	bool exit_after_sub; /* sub */
 	bool no_retain; /* sub */
 	bool retained_only; /* sub */
+	bool remove_retained; /* sub */
 	char **filter_outs; /* sub */
 	int filter_out_count; /* sub */
 	char **unsub_topics; /* sub */

client/sub_client.c

@@ -39,6 +39,7 @@ static struct mosq_config cfg;
 bool process_messages = true;
 int msg_count = 0;
 struct mosquitto *mosq = NULL;
+int last_mid = 0;
 
 #ifndef WIN32
 void my_signal_handler(int signum)
@@ -53,6 +54,14 @@ void my_signal_handler(int signum)
 void print_message(struct mosq_config *cfg, const struct mosquitto_message *message);
 
 
+void my_publish_callback(struct mosquitto *mosq, void *obj, int mid, int reason_code, const mosquitto_property *properties)
+{
+	if(process_messages == false && (mid == last_mid || last_mid == 0)){
+		mosquitto_disconnect_v5(mosq, 0, cfg.disconnect_props);
+	}
+}
+
+
 void my_message_callback(struct mosquitto *mosq, void *obj, const struct mosquitto_message *message, const mosquitto_property *properties)
 {
 	int i;
@@ -60,9 +69,15 @@ void my_message_callback(struct mosquitto *mosq, void *obj, const struct mosquit
 
 	if(process_messages == false) return;
 
+	if(cfg.remove_retained && message->retain){
+		mosquitto_publish(mosq, &last_mid, message->topic, 0, NULL, 1, true);
+	}
+
 	if(cfg.retained_only && !message->retain && process_messages){
 		process_messages = false;
-		mosquitto_disconnect_v5(mosq, 0, cfg.disconnect_props);
+		if(last_mid == 0){
+			mosquitto_disconnect_v5(mosq, 0, cfg.disconnect_props);
+		}
 		return;
 	}
 
@@ -80,7 +95,9 @@ void my_message_callback(struct mosquitto *mosq, void *obj, const struct mosquit
 		msg_count++;
 		if(cfg.msg_count == msg_count){
 			process_messages = false;
-			mosquitto_disconnect_v5(mosq, 0, cfg.disconnect_props);
+			if(last_mid == 0){
+				mosquitto_disconnect_v5(mosq, 0, cfg.disconnect_props);
+			}
 		}
 	}
 }
@@ -136,7 +153,7 @@ void print_usage(void)
 	printf("mosquitto_sub version %s running on libmosquitto %d.%d.%d.\n\n", VERSION, major, minor, revision);
 	printf("Usage: mosquitto_sub {[-h host] [-p port] [-u username [-P password]] -t topic | -L URL [-t topic]}\n");
 	printf("                     [-c] [-k keepalive] [-q qos]\n");
-	printf("                     [-C msg_count] [-E] [-R] [--retained-only] [-T filter_out] [-U topic ...]\n");
+	printf("                     [-C msg_count] [-E] [-R] [--retained-only] [--remove-retained] [-T filter_out] [-U topic ...]\n");
 	printf("                     [-F format]\n");
 #ifndef WIN32
 	printf("                     [-W timeout_secs]\n");
@@ -199,6 +216,8 @@ void print_usage(void)
 	printf(" --quiet : don't print error messages.\n");
 	printf(" --retained-only : only handle messages with the retained flag set, and exit when the\n");
 	printf("                   first non-retained message is received.\n");
+	printf(" --remove-retained : send a message to the server to clear any received retained messages\n");
+	printf("                     Use -T to filter out messages you do not want to be cleared.\n");
 	printf(" --will-payload : payload for the client Will, which is sent by the broker in case of\n");
 	printf("                  unexpected disconnection. If not given and will-topic is set, a zero\n");
 	printf("                  length message will be sent.\n");

man/mosquitto_sub.1.xml

@@ -43,6 +43,7 @@
 			<arg><option>-k</option> <replaceable>keepalive-time</replaceable></arg>
 			<arg><option>-N</option></arg>
 			<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
+			<arg><option>--remove-retained</option></arg>
 			<group choice='opt'>
 				<arg choice='plain'><option>-R</option></arg>
 				<arg choice='plain'><option>--retained-only</option></arg>
@@ -471,6 +472,36 @@
 						their display.</para>
 				</listitem>
 			</varlistentry>
+			<varlistentry>
+				<term><option>--remove-retained</option></term>
+				<listitem>
+					<para>If this argument is given, the when mosquitto_sub
+						receives a message with the retained bit set, it will
+						send a message to the broker to clear that retained
+						message. This applies to all received messages except
+						those that are filtered out by the <option>-T</option>
+						option. This option still takes effect even if
+						<option>-R</option> is used.  See also the
+						<option>--retain-as-published</option> and
+						<option>--retained-only</option> options.</para>
+
+						<example title="remove-retained-example-1" label="1">
+						<para>Remove all retained messages on the server,
+							assuming we have access to do so, and then exit:</para>
+
+						<programlisting language="config">
+mosquitto_sub -t '#' --remove-retained --retained-only</programlisting>
+						</example>
+
+						<example title="remove-retained-example-2" label="2">
+						<para>Remove a whole tree, with the exception of a
+							single topic:</para>
+
+						<programlisting language="config">
+mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained</programlisting>
+						</example>
+				</listitem>
+			</varlistentry>
 			<varlistentry>
 				<term><option>--retained-only</option></term>
 				<listitem>