diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt index e6edbe2..8e05502 100644 --- a/.github/.cSpellWords.txt +++ b/.github/.cSpellWords.txt @@ -22,11 +22,13 @@ cbor cmock coverity ctest +isjobupdatestatus jobz lcov litani misra notifyzz +otaparser rejectedzz sinclude strn diff --git a/.github/linkAllowList.txt b/.github/linkAllowList.txt deleted file mode 100644 index 73c1ee4..0000000 --- a/.github/linkAllowList.txt +++ /dev/null @@ -1,2 +0,0 @@ -https://s3.region.amazonaws.com/joe-ota/ -https://www.misra.org.uk diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0016180..9cf00d2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -108,7 +108,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main with: - allowlist-file: ./.github/linkAllowList.txt + exclude-urls: https://s3.region.amazonaws.com/joe-ota, https://www.misra.org.uk verify-manifest: runs-on: ubuntu-latest diff --git a/docs/doxygen/config.doxyfile b/docs/doxygen/config.doxyfile index 079477f..57aa102 100644 --- a/docs/doxygen/config.doxyfile +++ b/docs/doxygen/config.doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.9.6 +# Doxyfile 1.9.8 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -872,7 +872,14 @@ WARN_IF_UNDOC_ENUM_VAL = NO # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO @@ -919,6 +926,7 @@ WARN_LOGFILE = INPUT = ./docs/doxygen \ ./source/include \ + ./source/otaJobParser/include \ ./source # This tag can be used to specify the character encoding of the source files @@ -952,12 +960,12 @@ INPUT_FILE_ENCODING = # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, -# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C -# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, -# *.vhdl, *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, +# *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, *.php, +# *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be +# provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.h \ @@ -999,9 +1007,6 @@ EXCLUDE_PATTERNS = # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = @@ -1010,6 +1015,7 @@ EXCLUDE_SYMBOLS = # command). EXAMPLE_PATH = source/include \ + source/otaJobParser/include \ docs/doxygen/include # If the value of the EXAMPLE_PATH tag contains directories, you can use the @@ -1345,15 +1351,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will @@ -1991,9 +1988,16 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2014,14 +2018,6 @@ LATEX_HIDE_INDICES = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -2187,7 +2183,7 @@ DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. @@ -2336,15 +2332,15 @@ TAGFILES = GENERATE_TAGFILE = docs/doxygen/output/jobs.tag -# If the ALLEXTERNALS tag is set to YES, all external class will be listed in -# the class index. If set to NO, only the inherited external classes will be -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2358,16 +2354,9 @@ EXTERNAL_GROUPS = NO EXTERNAL_PAGES = NO #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2376,7 +2365,7 @@ HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO # The default value is: NO. @@ -2429,13 +2418,15 @@ DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a -# graph for each documented class showing the direct and indirect inheritance -# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, -# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set -# to TEXT the direct and indirect inheritance relations will be shown as texts / -# links. -# Possible values are: NO, YES, TEXT and GRAPH. +# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will +# generate a graph for each documented class showing the direct and indirect +# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and +# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case +# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the +# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. +# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance +# relations will be shown as texts / links. +# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. CLASS_GRAPH = YES @@ -2443,15 +2434,21 @@ CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the -# class with other documented classes. +# class with other documented classes. Explicit enabling a collaboration graph, +# when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the +# command \collaborationgraph. Disabling a collaboration graph can be +# accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. See also the chapter Grouping -# in the manual. +# groups, showing the direct groups dependencies. Explicit enabling a group +# dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means +# of the command \groupgraph. Disabling a directory graph can be accomplished by +# means of the command \hidegroupgraph. See also the chapter Grouping in the +# manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2511,7 +2508,9 @@ TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, +# can be accomplished by means of the command \includegraph. Disabling an +# include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2520,7 +2519,10 @@ INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set +# to NO, can be accomplished by means of the command \includedbygraph. Disabling +# an included by graph can be accomplished by means of the command +# \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2560,7 +2562,10 @@ GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the -# files in the directories. +# files in the directories. Explicit enabling a directory graph, when +# DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command +# \directorygraph. Disabling a directory graph can be accomplished by means of +# the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2576,7 +2581,7 @@ DIR_GRAPH_MAX_DEPTH = 1 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: -# http://www.graphviz.org/)). +# https://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). @@ -2613,11 +2618,12 @@ DOT_PATH = DOTFILE_DIRS = -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the \mscfile -# command). +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCFILE_DIRS = +DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile @@ -2694,3 +2700,9 @@ GENERATE_LEGEND = YES # The default value is: YES. DOT_CLEANUP = YES + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = diff --git a/docs/doxygen/pages.dox b/docs/doxygen/pages.dox index edc8bec..e641bda 100644 --- a/docs/doxygen/pages.dox +++ b/docs/doxygen/pages.dox @@ -8,7 +8,13 @@ AWS IoT jobs can be used to define a set of remote operations that are sent to a For documentation of the service, please see the [AWS IoT Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html). Interactions with the jobs service use MQTT, a lightweight publish-subscribe protocol. This library provides a convenience API to compose and recognize the MQTT topic strings used by the jobs service. -The library is written in C and designed to be compliant with ISO C90 and MISRA C:2012. +The library is written in C and designed to be compliant with ISO C99 and MISRA C:2012. +It has proofs showing safe memory use and no heap allocation, making it suitable for IoT microcontrollers, but also fully portable to other platforms. +

+ +

+AWS IoT OTA Job Parser can be used to Parse out the fields of an incoming Job Document sent to a device from AWS IoT. +The library is written in C and designed to be compliant with ISO C99 and MISRA C:2012. It has proofs showing safe memory use and no heap allocation, making it suitable for IoT microcontrollers, but also fully portable to other platforms.

@@ -57,14 +63,20 @@ These configuration settings are C pre-processor constants they are set using a */ /** -@page jobs_functions Functions +@page jobs_functions Jobs Functions @brief Primary functions of the Jobs library:

@subpage jobs_gettopic_function
@subpage jobs_matchtopic_function
@subpage jobs_getpending_function
@subpage jobs_startnext_function
+@subpage jobs_startnextmsg_function
@subpage jobs_describe_function
@subpage jobs_update_function
+@subpage jobs_updatemsg_function
+@subpage jobs_getjobid_function
+@subpage jobs_getjobdocument_function
+@subpage jobs_isstartnextaccepted_function
+@subpage jobs_isjobupdatestatus_function
@page jobs_gettopic_function Jobs_GetTopic @snippet jobs.h declare_jobs_gettopic @@ -82,6 +94,10 @@ These configuration settings are C pre-processor constants they are set using a @snippet jobs.h declare_jobs_startnext @copydoc Jobs_StartNext +@page jobs_startnextmsg_function Jobs_StartNextMsg +@snippet jobs.h declare_jobs_startnextmsg +@copydoc Jobs_StartNextMsg + @page jobs_describe_function Jobs_Describe @snippet jobs.h declare_jobs_describe @copydoc Jobs_Describe @@ -89,6 +105,41 @@ These configuration settings are C pre-processor constants they are set using a @page jobs_update_function Jobs_Update @snippet jobs.h declare_jobs_update @copydoc Jobs_Update + +@page jobs_updatemsg_function Jobs_UpdateMsg +@snippet jobs.h declare_jobs_updatemsg +@copydoc Jobs_UpdateMsg + +@page jobs_getjobid_function Jobs_GetJobId +@snippet jobs.h declare_jobs_getjobid +@copydoc Jobs_GetJobId + +@page jobs_getjobdocument_function Jobs_GetJobDocument +@snippet jobs.h declare_jobs_getjobdocument +@copydoc Jobs_GetJobDocument + +@page jobs_isstartnextaccepted_function Jobs_IsStartNextAccepted +@snippet jobs.h declare_jobs_isstartnextaccepted +@copydoc Jobs_IsStartNextAccepted + +@page jobs_isjobupdatestatus_function Jobs_IsJobUpdateStatus +@snippet jobs.h declare_jobs_isjobupdatestatus +@copydoc Jobs_IsJobUpdateStatus +*/ + +/** +@page ota_parser_functions OTA Job Parser Functions +@brief Primary Functions of the OTA Job Parser library:

+@subpage populatejobdocfields_function
+@subpage otaparser_parsejobdocfile_function
+ +@page populatejobdocfields_function populateJobDocFields +@snippet job_parser.h declare_populatejobdocfields +@copydoc populateJobDocFields + +@page otaparser_parsejobdocfile_function otaParser_parseJobDocFile +@snippet ota_job_processor.h declare_otaparser_parsejobdocfile +@copydoc otaParser_parseJobDocFile */ /** @@ -100,3 +151,8 @@ These configuration settings are C pre-processor constants they are set using a @defgroup jobs_constants Constants @brief Constants defined in the Jobs library */ + +/** +@defgroup jobs_structs Structs +@brief Structs defined in the Jobs Library +*/ diff --git a/source/include/jobs.h b/source/include/jobs.h index 54ad4ac..a7d935e 100644 --- a/source/include/jobs.h +++ b/source/include/jobs.h @@ -46,8 +46,19 @@ * @ingroup jobs_constants * @brief Size of Topic Buffer */ -#define TOPIC_BUFFER_SIZE 256U +#define TOPIC_BUFFER_SIZE 256U +/** + * @ingroup jobs_constants + * @brief Size of Jobs Start Next Message Buffer + */ +#define START_JOB_MSG_LENGTH 147U + +/** + * @ingroup jobs_constants + * @brief Size of Jobs Update Message Buffer + */ +#define UPDATE_JOB_MSG_LENGTH 48U /** * @ingroup jobs_constants @@ -633,11 +644,39 @@ JobsStatus_t Jobs_StartNext( char * buffer, * * @return 0 if write to buffer fails * @return The message length if the write is successful + * + * Example + * @code{c} + * + * + * // The Following Example shows usage of the Jobs_StartNextMsg API + * // to generate a message string for a StartNextPendingJobExecution request. + * + * const char * clientToken = "test"; + * size_t clientTokenLength = ( sizeof( clientToken ) - 1U ); + * char messageBuffer[ START_JOB_MSG_LENGTH ] = {0}; + * size_t messageLength = 0U; + * + * messageLength = Jobs_StartNextMsg( clientToken, + * clientTokenLength, + * messageBuffer, + * START_JOB_MSG_LENGTH ); + * + * if ( messageLength > 0 ) + * { + * // The message string of the clientToken has been generated in + * // the buffer, messageBuffer, for the StartNextPendingJobExecution request + * // Publish to the topic string generated by Jobs_StartNext() using an + * // MQTT client of your choice. + * } + * @endcode */ +/* @[declare_jobs_startnextmsg] */ size_t Jobs_StartNextMsg( const char * clientToken, size_t clientTokenLength, char * buffer, size_t bufferSize ); +/* @[declare_jobs_startnextmsg] */ /** * @brief Populate a topic string for a DescribeJobExecution request. @@ -807,24 +846,78 @@ JobsStatus_t Jobs_Update( char * buffer, * * @return 0 if write to buffer fails * @return messageLength if the write is successful + * + * Example + * @code{c} + * + * // The Following Example shows usage of the Jobs_UpdateMsg API to + * // generate a message string for the UpdateJobExecution API + * // of the AWS IoT Jobs Service + * const char * expectedVersion = "2"; + * size_t expectedVersionLength = ( sizeof(expectedVersion ) - 1U ); + * JobCurrentStatus_t status = Succeeded; + * char messageBuffer[ UPDATE_JOB_MSG_LENGTH ] = {0}; + * size_t messageLength = 0U; + * + * messageLength = Jobs_UpdateMsg( status, + * expectedVersion, + * expectedVersionLength, + * messageBuffer, + * UPDATE_JOB_MSG_LENGTH ); + * + * if (messageBufferLength > 0 ) + * { + * // The message string of length, messageLength, has been + * // generated in the buffer, messageBuffer, for the UpdateJobExecution API + * // Publish this message to the topic generated by Jobs_Update using an + * // MQTT client of your choice. + * } + * @endcode */ +/* @[declare_jobs_updatemsg] */ size_t Jobs_UpdateMsg( JobCurrentStatus_t status, const char * expectedVersion, size_t expectedVersionLength, char * buffer, size_t bufferSize ); +/* @[declare_jobs_updatemsg] */ /** * @brief Retrieves the job ID from a given message (if applicable) * - * @param message [In] A JSON formatted message which + * @param message [In] A JSON formatted message * @param messageLength [In] The length of the message * @param jobId [Out] The job ID * @return size_t The job ID length + * + * Example + * @code{c} + * + * // The following example shows the usage of the Jobs_GetJobId API to + * // extract the jobId and its length from a message, if present. + * + * const char * message; // A JSON formatted message from the IoT core + * size_t messageLength; // Length of the JSON formatted message + * const char * jobId; // variable to hold jobId + * size_t jobIdLength = 0U; // Holds length of the jobId + * + * jobIdLength = Jobs_GetJobId( message, + * messageLength, + * &jobId); + * + * if ( jobIdLength > 0 ) + * { + * // Job ID was successfully extracted from the message + * // Store the Job ID so that it can be used as needed by other functions. + * // For example, as an input to Jobs_Update. + * } + * @endcode */ +/* @[declare_jobs_getjobid] */ size_t Jobs_GetJobId( const char * message, size_t messageLength, const char ** jobId ); +/* @[declare_jobs_getjobid] */ /** * @brief Retrieves the job document from a given message (if applicable) @@ -833,10 +926,36 @@ size_t Jobs_GetJobId( const char * message, * @param messageLength [In] The length of the message * @param jobDoc [Out] The job document * @return size_t The length of the job document + * + * Example + * @code{c} + * + * // The following example shows the usage of the Jobs_GetJobId API to + * // extract the jobId and its length from a message, if present. + * + * const char * message; // A JSON formatted message from the IoT core + * size_t messageLength; // Length of the JSON formatted message + * const char * jobDoc; // variable to hold the job doc + * size_t jobDocLength = 0U; // Holds length of the job doc + * + * jobDocLength = Jobs_GetJobDocument( message, + * messageLength, + * &jobDoc); + * + * if ( jobDocLength > 0 ) + * { + * // JobDoc was successfully extracted from the message. + * // Pass JobDoc as input to otaParser_parseJobDocFile to + * // extract the fields from the job document and store them + * // in a AfrOtaJobDocumentFields_t stuct. + * } + * @endcode */ +/* @[declare_jobs_getjobdocument] */ size_t Jobs_GetJobDocument( const char * message, size_t messageLength, const char ** jobDoc ); +/* @[declare_jobs_getjobdocument] */ /** * @brief Checks if a message comes from the start-next/accepted reserved topic @@ -847,11 +966,14 @@ size_t Jobs_GetJobDocument( const char * message, * @param thingNameLength The length of the thingName. * @return true If the topic is the start-next/accepted topic * @return false If the topic is not the start-next/accepted topic + * */ +/* @[declare_jobs_isstartnextaccepted] */ bool Jobs_IsStartNextAccepted( const char * topic, const size_t topicLength, const char * thingName, const size_t thingNameLength ); +/* @[declare_jobs_isstartnextaccepted] */ /** * @brief Checks if a message comes from the update/accepted reserved topic @@ -866,6 +988,7 @@ bool Jobs_IsStartNextAccepted( const char * topic, * @return true If the topic is the update/\ topic * @return false If the topic is not the update/\ topic */ +/* @[declare_jobs_isjobupdatestatus] */ bool Jobs_IsJobUpdateStatus( const char * topic, const size_t topicLength, const char * jobId, @@ -873,6 +996,7 @@ bool Jobs_IsJobUpdateStatus( const char * topic, const char * thingName, const size_t thingNameLength, JobUpdateStatus_t expectedStatus ); +/* @[declare_jobs_isjobupdatestatus] */ /* *INDENT-OFF* */ diff --git a/source/otaJobParser/include/job_parser.h b/source/otaJobParser/include/job_parser.h index 875646a..23ced31 100644 --- a/source/otaJobParser/include/job_parser.h +++ b/source/otaJobParser/include/job_parser.h @@ -14,20 +14,49 @@ #include #include +/** + * @ingroup jobs_structs + * @brief struct containing the fields of an AFR OTA Job Document + */ typedef struct { + /** @brief Code Signing Signature */ const char * signature; + + /** @brief Length of signature */ size_t signatureLen; + + /** @brief File path to store OTA Update on device */ const char * filepath; + + /** @brief Length of filepath */ size_t filepathLen; + + /** @brief Path to Code Signing Certificate on Device */ const char * certfile; + + /** @brief Length of certfile */ size_t certfileLen; + + /** @brief Authentication Scheme for HTTP URL ( null for MQTT ) */ const char * authScheme; + + /** @brief Length of authScheme */ size_t authSchemeLen; + + /** @brief MQTT Stream or HTTP URL */ const char * imageRef; + + /** @brief Length of imageRef */ size_t imageRefLen; + + /** @brief File ID */ uint32_t fileId; + + /** @brief Size of the OTA Update */ uint32_t fileSize; + + /** @brief File Type */ uint32_t fileType; } AfrOtaJobDocumentFields_t; @@ -42,9 +71,11 @@ typedef struct * @return true Job document fields were parsed from the document * @return false Job document fields were not parsed from the document */ +/* @[declare_populatejobdocfields] */ bool populateJobDocFields( const char * jobDoc, const size_t jobDocLength, int32_t fileIndex, AfrOtaJobDocumentFields_t * result ); +/* @[declare_populatejobdocfields] */ #endif /* JOB_PARSER_H */ diff --git a/source/otaJobParser/include/ota_job_processor.h b/source/otaJobParser/include/ota_job_processor.h index 5333964..00473c4 100644 --- a/source/otaJobParser/include/ota_job_processor.h +++ b/source/otaJobParser/include/ota_job_processor.h @@ -17,9 +17,42 @@ #include "job_parser.h" +/** + * @brief Signals if the job document provided is an AWS IoT Core OTA update document + * + * @param jobDoc The job document contained in the AWS IoT Job + * @param jobDocLength The length of the job document + * @param fields A pointer to an job document fields structure populated by call + * @return int8_t The next file index in the job. Returns 0 if no additional files are available. Returns -1 if error. + * + * Example + * @code{c} + * + * // The following example shows how to use the otaParser_parseJobDocFile API + * // to parse out the fields of a received Job Document and populate the fields + * // of the AfrOtaJobDocumentFields_t stucture. + * + * const char * jobDoc; // Populated by call to Jobs_GetJobDocument + * size_t jobDocLength; // Return value of Jobs_GetJobDocument + * int8_t fileIndex = 0; + * AfrOtaJobDocumentFields_t fields = {0}; // populated by API + * + * do + * { + * fileIndex = otaParser_parseJobDocFile(jobDoc, + * jobDocLength, + * fileIndex, + * &fields); + * } while(fileIndex > 0) + * // File index will be -1 if an error occurred, and 0 if all files were + * // processed + * @endcode + */ +/* @[declare_otaparser_parsejobdocfile] */ int8_t otaParser_parseJobDocFile( const char * jobDoc, const size_t jobDocLength, const uint8_t fileIndex, AfrOtaJobDocumentFields_t * fields ); +/* @[declare_otaparser_parsejobdocfile] */ #endif /*OTA_JOB_PROCESSOR_H*/