Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update doxygen documentation
Browse files Browse the repository at this point in the history
bradleysmith23 committed Nov 10, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 89fd1f7 commit abe1266
Showing 5 changed files with 356 additions and 65 deletions.
210 changes: 147 additions & 63 deletions docs/doxygen/config.doxyfile
Original file line number Diff line number Diff line change
@@ -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 <return> 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,29 +2480,37 @@ 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

# 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
# <outfile_format> -o <outputfile> <inputfile>. 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 =
47 changes: 46 additions & 1 deletion docs/doxygen/pages.dox
Original file line number Diff line number Diff line change
@@ -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:<br><br>
@subpage jobs_gettopic_function <br>
@subpage jobs_matchtopic_function <br>
@subpage jobs_getpending_function <br>
@subpage jobs_startnext_function <br>
@subpage jobs_startnextmsg_function <br>
@subpage jobs_describe_function <br>
@subpage jobs_update_function <br>
@subpage jobs_updatemsg_function <br>
@subpage jobs_getjobid_function <br>
@subpage jobs_getjobdocument_function <br>
@subpage jobs_isstartnextaccepted_function <br>
@subpage jobs_isjobupdatestatus_function <br>

@page jobs_gettopic_function Jobs_GetTopic
@snippet jobs.h declare_jobs_gettopic
@@ -82,13 +88,52 @@ 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

@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:<br><br>
@subpage populatejobdocfields_function <br>
@subpage otaparser_parsejobdocfile_function <br>

@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
*/

/**
126 changes: 125 additions & 1 deletion source/include/jobs.h
Original file line number Diff line number Diff line change
@@ -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
*
* <b>Example</b>
* @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
*
* <b>Example</b>
* @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
*
* <b>Example</b>
* @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
*
* <b>Example</b>
* @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,13 +988,15 @@ bool Jobs_IsStartNextAccepted( const char * topic,
* @return true If the topic is the update/\<expectedStatus\> topic
* @return false If the topic is not the update/\<expectedStatus\> topic
*/
/* @[declare_jobs_isjobupdatestatus] */
bool Jobs_IsJobUpdateStatus( const char * topic,
const size_t topicLength,
const char * jobId,
const size_t jobIdLength,
const char * thingName,
const size_t thingNameLength,
JobUpdateStatus_t expectedStatus );
/* @[declare_jobs_isjobupdatestatus] */


/* *INDENT-OFF* */
5 changes: 5 additions & 0 deletions source/otaJobParser/include/job_parser.h
Original file line number Diff line number Diff line change
@@ -14,6 +14,9 @@
#include <stdlib.h>
#include <stdint.h>

/**
* @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 */
33 changes: 33 additions & 0 deletions source/otaJobParser/include/ota_job_processor.h
Original file line number Diff line number Diff line change
@@ -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.
*
* <b>Example</b>
* @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*/

0 comments on commit abe1266

Please sign in to comment.