Add support for the job ID value, $next, in Jobs_Describe()

.github/workflows/ci.yml

@@ -66,7 +66,7 @@ jobs:
       - uses: actions/checkout@v2
       - name: Install Doxygen
         run: |
-          wget -qO- "http://doxygen.nl/files/doxygen-1.8.20.linux.bin.tar.gz" | sudo tar --strip-components=1 -xz -C /usr/local
+          wget -qO- "http://doxygen.nl/files/doxygen-1.9.1.linux.bin.tar.gz" | sudo tar --strip-components=1 -xz -C /usr/local
           sudo apt-get install -y libclang-9-dev
       - name: Run Doxygen And Verify Stdout Is Empty
         run: |

docs/doxygen/config.doxyfile

@@ -928,13 +928,6 @@ VERBATIM_HEADERS       = YES
 
 ALPHABETICAL_INDEX     = YES
 
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX    = 5
-
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output
 #---------------------------------------------------------------------------

source/include/jobs.h

@@ -105,6 +105,9 @@
 #define JOBS_API_UPDATE                   "update"
 #define JOBS_API_UPDATE_LENGTH            ( sizeof( JOBS_API_UPDATE ) - 1U )
 
+#define JOBS_API_JOBID_NEXT               "$next"
+#define JOBS_API_JOBID_NEXT_LENGTH        ( sizeof( JOBS_API_JOBID_NEXT ) - 1U )
+
 #define JOBS_API_COMMON_LENGTH( thingNameLength ) \
     ( JOBS_API_PREFIX_LENGTH + ( thingNameLength ) + JOBS_API_BRIDGE_LENGTH )
 
@@ -302,6 +305,9 @@ JobsStatus_t Jobs_StartNext( char * buffer,
  * the buffer up to one less than the buffer size.  The topic is
  * ended with a NUL character.
  *
+ * @note A jobId consisting of the string, "$next", is supported to generate
+ * a topic string to request the next pending job.
+ *
  * @note The thingName and jobId parameters do not need a NULL terminator.
  */
 /* @[declare_jobs_describe] */

source/jobs.c

@@ -600,6 +600,29 @@ JobsStatus_t Jobs_StartNext( char * buffer,
     return ret;
 }
 
+/**
+ * @brief Predicate returns true for a match to JOBS_API_JOBID_NEXT
+ *
+ * @param[in] jobId  character sequence to check
+ * @param[in] jobIdLength  length of the character sequence
+ *
+ * @return true if the job ID matches;
+ * false otherwise
+ */
+static bool_ isNextJobId( const char * jobId,
+                          uint16_t jobIdLength )
+{
+    bool_ ret = false;
+
+    if( ( jobId != NULL ) &&
+        ( strnnEq( JOBS_API_JOBID_NEXT, JOBS_API_JOBID_NEXT_LENGTH, jobId, jobIdLength ) == JobsSuccess ) )
+    {
+        ret = true;
+    }
+
+    return ret;
+}
+
 /**
  * See jobs.h for docs.
  *
@@ -617,7 +640,8 @@ JobsStatus_t Jobs_Describe( char * buffer,
     size_t start = 0U;
 
     if( checkCommonParams() &&
-        ( isValidJobId( jobId, jobIdLength ) == true ) )
+        ( ( isNextJobId( jobId, jobIdLength ) == true ) ||
+          ( isValidJobId( jobId, jobIdLength ) == true ) ) )
     {
         writePreamble( buffer, &start, length, thingName, thingNameLength );
 

test/cbmc/proofs/Jobs_Describe/Makefile

@@ -13,6 +13,7 @@ EXCEED_JOBID_MAX_LENGTH=7
 REMOVE_FUNCTION_BODY +=
 # Use the largest of the above
 UNWINDSET += isValidID.0:$(EXCEED_THINGNAME_MAX_LENGTH)
+UNWINDSET += strnEq.0:$(EXCEED_JOBID_MAX_LENGTH)
 
 # Use a stub in place of the original function.
 PROOF_SOURCES += $(PROOF_STUB)/strnAppend.c

test/unit-test/jobs_utest.c

@@ -162,6 +162,10 @@ void test_Jobs_bad_parameters( void )
     TEST_BAD_PARAMETER( Jobs_Describe( buf, sizeof( buf ), name_, ( THINGNAME_MAX_LENGTH + 1 ), jobId_, jobIdLength_, &outLength ) );
     TEST_BAD_PARAMETER( Jobs_Update( buf, sizeof( buf ), name_, ( THINGNAME_MAX_LENGTH + 1 ), jobId_, jobIdLength_, &outLength ) );
 
+    /* job ID is NULL */
+    TEST_BAD_PARAMETER( Jobs_Describe( buf, sizeof( buf ), name_, nameLength_, NULL, jobIdLength_, &outLength ) );
+    TEST_BAD_PARAMETER( Jobs_Update( buf, sizeof( buf ), name_, nameLength_, NULL, jobIdLength_, &outLength ) );
+
     /* bad job ID - variations tested separately */
     TEST_BAD_PARAMETER( Jobs_Describe( buf, sizeof( buf ), name_, nameLength_, "!", jobIdLength_, &outLength ) );
     TEST_BAD_PARAMETER( Jobs_Update( buf, sizeof( buf ), name_, nameLength_, "!", jobIdLength_, &outLength ) );
@@ -229,6 +233,10 @@ void test_Jobs_valid_identifiers( void )
             TEST_ASSERT_EQUAL( JobsBadParameter, ret );
         }
     }
+
+    /* Test additional valid jobId, $next */
+    ret = Jobs_Describe( buf, sizeof( buf ), name_, nameLength_, JOBS_API_JOBID_NEXT, JOBS_API_JOBID_NEXT_LENGTH, &outLength );
+    TEST_ASSERT_EQUAL( JobsSuccess, ret );
 }
 
 /**