From abe1266dd8e29657677ff5fd360a7d1551cb9b09 Mon Sep 17 00:00:00 2001 From: bradleysmith23 Date: Fri, 10 Nov 2023 12:31:08 -0800 Subject: [PATCH] Update doxygen documentation --- docs/doxygen/config.doxyfile | 210 ++++++++++++------ docs/doxygen/pages.dox | 47 +++- source/include/jobs.h | 126 ++++++++++- source/otaJobParser/include/job_parser.h | 5 + .../otaJobParser/include/ota_job_processor.h | 33 +++ 5 files changed, 356 insertions(+), 65 deletions(-) diff --git a/docs/doxygen/config.doxyfile b/docs/doxygen/config.doxyfile index 079477f2..76873602 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. @@ -363,6 +363,17 @@ MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_ID_STYLE = DOXYGEN + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -487,6 +498,14 @@ LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -872,7 +891,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 +945,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 +979,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 +1026,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 +1034,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 +1370,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 @@ -1373,6 +1389,13 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1503,6 +1526,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1991,9 +2024,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 +2054,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,13 +2219,39 @@ 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. GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- + +# If the GENERATE_SQLITE3 tag is set to YES doxygen will generate a Sqlite3 +# database with symbols found by doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_OVERWRITE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each doxygen run. If set to NO, doxygen +# will warn if an a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- @@ -2336,15 +2394,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 +2416,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 +2427,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 +2480,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 +2496,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 +2570,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 +2581,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 +2624,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 +2643,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 +2680,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 +2762,19 @@ GENERATE_LEGEND = YES # The default value is: YES. DOT_CLEANUP = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will +# use a built-in version of mscgen tool to produce the charts. Alternatively, +# the MSCGEN_TOOL tag can also specify the name an external tool. For instance, +# specifying prog as the value, doxygen will call the tool as prog -T +# -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# 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 edc8becf..dc147886 100644 --- a/docs/doxygen/pages.dox +++ b/docs/doxygen/pages.dox @@ -57,14 +57,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 +88,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 +99,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 */ /** diff --git a/source/include/jobs.h b/source/include/jobs.h index 54ad4ac9..580c21cc 100644 --- a/source/include/jobs.h +++ b/source/include/jobs.h @@ -48,6 +48,17 @@ */ #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 875646ad..f457bd07 100644 --- a/source/otaJobParser/include/job_parser.h +++ b/source/otaJobParser/include/job_parser.h @@ -14,6 +14,9 @@ #include #include +/** + * @brief struct containing the fields of an AFR OTA Job Document +*/ typedef struct { const char * signature; @@ -42,9 +45,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 53339648..1ac6390a 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 a FreeRTOS 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 occured, 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*/