Add links to the MQTT agent in the non-agent mqtt demos (FreeRTOS#470)

Add URL file links to the MQTT agent documentation page.
Add comment blocks into each demo that also point toward the MQTT agent documentation to ensure users are aware the agent method exists.

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/Common/main.c

@@ -25,7 +25,23 @@
  */
 
 /***
- * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions.
+ * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions,
+ * and https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an alternative
+ * usage model that runs MQTT in an autonomous background agent task.  See the
+ * note below.
+ *
+ * Note: Single Threaded Vs Multi Threaded
+ * There are two coreMQTT usage models, single threaded and multithreaded
+ * (multitasking). Using the MQTT library solely from one thread within an
+ * otherwise multi-threaded application, as the demos in these subdirectories do,
+ * is equivalent to the single threaded use case. Single threaded use cases
+ * require the application writer to make repeated explicit calls into the MQTT
+ * library. Multithreaded use cases can instead execute the MQTT protocol in the
+ * background within an agent (or daemon) task. Executing the MQTT protocol in
+ * an agent task removes the need for the application writer to explicitly
+ * manage any MQTT state or call the MQTT_ProcessLoop() API function. Using an
+ * agent task also enables multiple application tasks to share a single MQTT
+ * connection without the need for synchronization primitives such as mutexes.
  ***/
 
 /* Standard includes. */
@@ -106,7 +122,23 @@ static UBaseType_t ulNextRand;
 int main( void )
 {
     /***
-     * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions.
+     * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions,
+     * and https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an alternative
+     * usage model that runs MQTT in an autonomous background agent task.  See the
+     * note below.
+     *
+     * Note: Single Threaded Vs Multi Threaded
+     * There are two coreMQTT usage models, single threaded and multithreaded
+     * (multitasking). Using the MQTT library solely from one thread within an
+     * otherwise multi-threaded application, as the demos in these subdirectories do,
+     * is equivalent to the single threaded use case. Single threaded use cases
+     * require the application writer to make repeated explicit calls into the MQTT
+     * library. Multithreaded use cases can instead execute the MQTT protocol in the
+     * background within an agent (or daemon) task. Executing the MQTT protocol in
+     * an agent task removes the need for the application writer to explicitly
+     * manage any MQTT state or call the MQTT_ProcessLoop() API function. Using an
+     * agent task also enables multiple application tasks to share a single MQTT
+     * connection without the need for synchronization primitives such as mutexes.
      ***/
 
     /* Miscellaneous initialization including preparing the logging and seeding

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/DemoTasks/BasicTLSMQTTExample.c

@@ -37,6 +37,14 @@
  * broker in this example. Define democonfigMQTT_BROKER_ENDPOINT and
  * democonfigROOT_CA_PEM in demo_config.h to establish a server-authenticated
  * connection.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -185,8 +193,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -373,8 +381,16 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe, and disconnect from the MQTT
-     * broker. */
-    xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection. */
+     xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */
                  NULL,                     /* Task parameter - not used in this case. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/DemoTasks/KeepAliveMQTTExample.c

@@ -40,6 +40,14 @@
  * !!! NOTE !!!
  * This MQTT demo does not authenticate the server nor the client.
  * Hence, this demo should not be used as production ready code.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -207,8 +215,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -481,6 +489,13 @@ void vStartSimpleMQTTDemo( void )
 }
 /*-----------------------------------------------------------*/
 
+ /* Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection. */
 static void prvMQTTDemoTask( void * pvParameters )
 {
     uint32_t ulTopicCount = 0U;

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/DemoTasks/MultitaskMQTTExample.c

@@ -28,6 +28,13 @@
  * This demo shows how to use coreMQTT in a multithreaded environment - it does not
  * yet go as far as encapsulating the MQTT library within its own agent (or daemon)
  * task - although the prvCommandLoop() function demonstrates how that might be done.
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * example that does use an agent task.  Executing the MQTT protocol in an agent
+ * task removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
+ *
  * In this task prvCommandLoop() is only executed from a single thread and is the
  * only function that is allowed to use the coreMQTT API directly.  Anything else
  * needing to interact with the coreMQTT API does so by posting commands to
@@ -375,8 +382,8 @@ typedef struct publishElement
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -2098,6 +2105,13 @@ static void prvCleanExistingPersistentSession( void )
 
 /*-----------------------------------------------------------*/
 
+ /* Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+  * alternative run time model whereby coreMQTT runs in an autonomous
+  * background agent task.  Executing the MQTT protocol in an agent task
+  * removes the need for the application writer to explicitly manage any MQTT
+  * state or call the MQTT_ProcessLoop() API function. Using an agent task
+  * also enables multiple application tasks to more easily share a single
+  * MQTT connection. */
 static void prvMQTTDemoTask( void * pvParameters )
 {
     BaseType_t xNetworkStatus = pdFAIL;

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/DemoTasks/MutualAuthMQTTExample.c

@@ -38,6 +38,14 @@
  * democonfigROOT_CA_PEM, democonfigCLIENT_CERTIFICATE_PEM,
  * and democonfigCLIENT_PRIVATE_KEY_PEM in demo_config.h to establish a
  * mutually authenticated connection.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -274,8 +282,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -462,7 +470,15 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe and disconnect from the MQTT
-     * broker. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection. */
     xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/DemoTasks/PlaintextMQTTExample.c

@@ -36,6 +36,14 @@
  * !!! NOTE !!!
  * This MQTT demo does not authenticate the server nor the client.
  * Hence, this demo should not be used as production ready code.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -176,8 +184,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -358,7 +366,15 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe and disconnect from the MQTT
-     * broker. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection.*/
     xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/readme_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?