Add macros to API for compile time topic generation

source/include/jobs.h

@@ -111,11 +111,96 @@
 #define JOBS_API_JOBID_NEXT               "$next"
 #define JOBS_API_JOBID_NEXT_LENGTH        ( sizeof( JOBS_API_JOBID_NEXT ) - 1U )
 
+#define JOBS_API_JOBID_NULL               ""
+#define JOBS_API_LEVEL_SEPARATOR          "/"
+
 #define JOBS_API_COMMON_LENGTH( thingNameLength ) \
     ( JOBS_API_PREFIX_LENGTH + ( thingNameLength ) + JOBS_API_BRIDGE_LENGTH )
 
 /** @endcond */
 
+
+/**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this macro as it is private.
+ */
+
+/* AWS IoT Jobs API topics. */
+#define JOBS_TOPIC_COMMON( thingName, jobId, jobsApi ) \
+    ( JOBS_API_PREFIX                                  \
+      thingName                                        \
+      JOBS_API_BRIDGE                                  \
+      jobId                                            \
+      jobsApi )
+/** @endcond */
+
+/**
+ * @ingroup jobs_constants
+ * @brief Topic string for subscribing to the NextJobExecutionChanged API.
+ *
+ * This macro should be used when the thing name is known at the compile time.
+ * If the thing name is not known at compile time, the #Jobs_GetTopic API
+ * should be used instead.
+ *
+ * @param thingName The thing name as registered with AWS IoT Core.
+ */
+#define JOBS_API_SUBSCRIBE_NEXTJOBCHANGED( thingName ) \
+    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_NEXTJOBCHANGED )
+
+/**
+ * @ingroup jobs_constants
+ * @brief Topic string for subscribing to the JobExecutionsChanged API.
+ *
+ * This macro should be used when the thing name is known at the compile time.
+ * If the thing name is not known at compile time, the #Jobs_GetTopic API
+ * should be used instead.
+ *
+ * @param thingName The thing name as registered with AWS IoT Core.
+ */
+#define JOBS_API_SUBSCRIBE_JOBSCHANGED( thingName ) \
+    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_JOBSCHANGED )
+
+/**
+ * @ingroup jobs_constants
+ * @brief Topic string for publishing to the StartNextPendingJobExecution API.
+ *
+ * This macro should be used when the thing name is known at the compile time.
+ * If the thing name is not known at compile time, the #Jobs_StartNext API
+ * should be used instead.
+ *
+ * @param thingName The thing name as registered with AWS IoT Core.
+ */
+#define JOBS_API_PUBLISH_STARTNEXT( thingName ) \
+    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_STARTNEXT )
+
+/**
+ * @ingroup jobs_constants
+ * @brief Topic string for publishing to the GetPendingJobExecutions API.
+ *
+ * This macro should be used when the thing name is known at the compile time.
+ * If the thing name is not known at compile time, the #Jobs_GetPending API
+ * should be used instead.
+ *
+ * @param thingName The thing name as registered with AWS IoT Core.
+ */
+#define JOBS_API_PUBLISH_GETPENDING( thingName ) \
+    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_GETPENDING )
+
+/**
+ * @ingroup jobs_constants
+ * @brief Topic string for querying the next pending job from the
+ * DescribeJobExecution API.
+ *
+ * This macro should be used when the thing name and jobID are known at the
+ * compile time. If next pending job is being queried, use $next as job ID.
+ * If the thing name or job ID are not known at compile time, the #Jobs_Describe API
+ * should be used instead.
+ *
+ * @param thingName The thing name as registered with AWS IoT Core.
+ */
+#define JOBS_API_PUBLISH_DESCRIBENEXTJOB( thingName ) \
+    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NEXT JOBS_API_LEVEL_SEPARATOR, JOBS_API_DESCRIBE )
+
 /**
  * @ingroup jobs_constants
  * @brief The size needed to hold the longest topic for a given thing name length.
@@ -192,6 +277,13 @@ typedef enum
  *
  * @note The thingName parameter does not need a NUL terminator.
  *
+ * @note The AWS IoT Jobs service does not require clients to subscribe
+ * to the "/accepted" and "/rejected" response topics for the APIs that
+ * accept requests on PUBLISH topics. The Jobs service will send responses
+ * to requests from clients irrespective of whether they have subscribed to
+ * response topics or not. For more information, refer to the AWS docs here:
+ * https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html
+ *
  * <b>Example</b>
  * @code{c}
  *
@@ -370,6 +462,14 @@ JobsStatus_t Jobs_MatchTopic( char * topic,
  *
  * @note The thingName parameter does not need a NUL terminator.
  *
+ * @note The AWS IoT Jobs service does not require clients to subscribe
+ * to the "/accepted" and "/rejected" response topics of the
+ * GetPendingJobExecutions API.
+ * The Jobs service will send responses to requests published to the API
+ * from clients irrespective of whether they have subscribed to response topics
+ * or not. For more information, refer to the AWS docs here:
+ * https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html
+ *
  * <b>Example</b>
  * @code{c}
  *
@@ -428,6 +528,14 @@ JobsStatus_t Jobs_GetPending( char * buffer,
  *
  * @note The thingName parameter does not need a NUL terminator.
  *
+ * @note The AWS IoT Jobs service does not require clients to subscribe
+ * to the "/accepted" and "/rejected" response topics of the
+ * StartNextPendingJobExecution API.
+ * The Jobs service will send responses to requests published to the API
+ * from clients irrespective of whether they have subscribed to response topics
+ * or not. For more information, refer to the AWS docs here:
+ * https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html
+ *
  * <b>Example</b>
  * @code{c}
  *
@@ -491,6 +599,14 @@ JobsStatus_t Jobs_StartNext( char * buffer,
  *
  * @note The thingName and jobId parameters do not need a NUL terminator.
  *
+ * @note The AWS IoT Jobs service does not require clients to subscribe
+ * to the "/accepted" and "/rejected" response topics of the
+ * DescribeJobExecution API.
+ * The Jobs service will send responses to requests published to the API
+ * from clients irrespective of whether they have subscribed to response topics
+ * or not. For more information, refer to the AWS docs here:
+ * https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html
+ *
  * <b>Example</b>
  * @code{c}
  *
@@ -560,6 +676,14 @@ JobsStatus_t Jobs_Describe( char * buffer,
  *
  * @note The thingName and jobId parameters do not need a NUL terminator.
  *
+ * @note The AWS IoT Jobs service does not require clients to subscribe
+ * to the "/accepted" and "/rejected" response topics of the
+ * UpdateJobExecution API.
+ * The Jobs service will send responses to requests published to the API
+ * from clients irrespective of whether they have subscribed to response topics
+ * or not. For more information, refer to the AWS docs here:
+ * https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html
+ *
  * <b>Example</b>
  * @code{c}
  *

test/unit-test/jobs_utest.c

@@ -42,6 +42,9 @@
 #define jobId_          "1234"
 #define jobIdLength_    ( sizeof( jobId_ ) - 1 )
 
+/* Common prefix of Jobs topics. */
+#define PREFIX          JOBS_API_PREFIX name_ JOBS_API_BRIDGE
+
 /* ============================   UNITY FIXTURES ============================ */
 
 /* Called before each test method. */
@@ -67,6 +70,35 @@ int suiteTearDown( int numFailures )
 
 /* ========================================================================== */
 
+/**
+ * @brief Test that the topic generating macros are valid.
+ */
+void test_JobsPUBLISH__API_macros_are_v( void )
+{
+    char * expectedTopic = NULL;
+
+    /* Test for NextJobExecutionChanged API topic. */
+    expectedTopic = PREFIX JOBS_API_NEXTJOBCHANGED;
+    TEST_ASSERT_EQUAL_STRING( expectedTopic, JOBS_API_SUBSCRIBE_NEXTJOBCHANGED( name_ ) );
+
+    /* Test for JobExecutionsChanged API topic. */
+    expectedTopic = PREFIX JOBS_API_JOBSCHANGED;
+    TEST_ASSERT_EQUAL_STRING( expectedTopic, JOBS_API_SUBSCRIBE_JOBSCHANGED( name_ ) );
+
+    /* Test for StartNextPendingJobExecution API topic. */
+    expectedTopic = PREFIX JOBS_API_STARTNEXT;
+    TEST_ASSERT_EQUAL_STRING( expectedTopic, JOBS_API_PUBLISH_STARTNEXT( name_ ) );
+
+    /* Test for GetPendingJobExecutions API topic. */
+    expectedTopic = PREFIX JOBS_API_GETPENDING;
+    TEST_ASSERT_EQUAL_STRING( expectedTopic, JOBS_API_PUBLISH_GETPENDING( name_ ) );
+
+    /* Test for DescribeJobExecution API topic for the "$next" job ID. */
+    expectedTopic = PREFIX JOBS_API_JOBID_NEXT "/" JOBS_API_DESCRIBE;
+    TEST_ASSERT_EQUAL_STRING( expectedTopic, JOBS_API_PUBLISH_DESCRIBENEXTJOB( name_ ) );
+}
+
+
 /**
  * @brief Test that all topic enums are contiguous
  *
@@ -251,7 +283,7 @@ void test_Jobs_buffer_lengths( void )
     JobsStatus_t ret;
     size_t len;
     unsigned i = 0;
-    char expected1[] = JOBS_API_PREFIX name_ JOBS_API_BRIDGE JOBS_API_JOBSCHANGED;
+    char expected1[] = JOBS_API_SUBSCRIBE_JOBSCHANGED( name_ );
     char expected2[] = JOBS_API_PREFIX name_ JOBS_API_BRIDGE "+/" JOBS_API_UPDATE JOBS_API_SUCCESS;
 
     ret = Jobs_GetTopic( buf, sizeof( buf ), name_, nameLength_, JobsJobsChanged, NULL );
@@ -281,7 +313,6 @@ void test_Jobs_happy_path( void )
     char buf[ JOBS_API_MAX_LENGTH( nameLength_ ) ];
     size_t outLength;
 
-#define PREFIX    JOBS_API_PREFIX name_ JOBS_API_BRIDGE
     char prefix[] = PREFIX;
 
 #define TEST_SUCCESS( x )                          \
@@ -300,7 +331,7 @@ void test_Jobs_happy_path( void )
     TEST_ASSERT_EQUAL( ( sizeof( x ) - 1 ), outLength )
 
     {
-        char expected[] = PREFIX JOBS_API_GETPENDING;
+        char expected[] = JOBS_API_PUBLISH_GETPENDING( name_ );
 
         TEST_SUCCESS( Jobs_GetPending( buf, sizeof( buf ), name_, nameLength_, NULL ) );
         TEST_SUCCESS( Jobs_GetPending( buf, sizeof( buf ), name_, nameLength_, &outLength ) );
@@ -312,7 +343,7 @@ void test_Jobs_happy_path( void )
     }
 
     {
-        char expected[] = PREFIX JOBS_API_STARTNEXT;
+        char expected[] = JOBS_API_PUBLISH_STARTNEXT( name_ );
 
         TEST_SUCCESS( Jobs_StartNext( buf, sizeof( buf ), name_, nameLength_, NULL ) );
         TEST_SUCCESS( Jobs_StartNext( buf, sizeof( buf ), name_, nameLength_, &outLength ) );