Added partial documentation of DS-COV.

Dropped the Latex output from default doxyfile. Added a convenience starting point for HTML output, the only format that has worked well for this project on doxygen.
2010-03-07 05:42:19 +00:00
parent 997a75ecfe
commit 776bf54278
5 changed files with 100 additions and 14 deletions
@@ -529,7 +529,7 @@ FILE_PATTERNS =
 # should be searched for input files as well. Possible values are YES and NO. 
 # If left blank NO is used.

-RECURSIVE = NO
+RECURSIVE = YES

 # The EXCLUDE tag can be used to specify files and/or directories that should 
 # excluded from the INPUT source files. This way you can easily exclude a 
@@ -781,7 +781,7 @@ HTML_DYNAMIC_SECTIONS = NO
 # can add a path in front of the file if the result should not be 
 # written to the html output directory.

-CHM_FILE = 
+CHM_FILE = BAC-stack.chm

 # If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can 
 # be used to specify the location (absolute path including file name) of 
@@ -840,7 +840,7 @@ TREEVIEW_WIDTH = 250
 # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will 
 # generate Latex output.

-GENERATE_LATEX = YES
+GENERATE_LATEX = NO

 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. 
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 
@@ -938,7 +938,7 @@ COMPACT_RTF = NO
 # programs which support those fields. 
 # Note: wordpad (write) and others do not support links.

-RTF_HYPERLINKS = NO
+RTF_HYPERLINKS = YES

 # Load stylesheet definitions from file. Syntax is similar to doxygen's 
 # config file, i.e. a series of assignments. You only have to provide 
@@ -1208,14 +1208,14 @@ HAVE_DOT = NO
 # indirect inheritance relations. Setting this tag to YES will force the 
 # the CLASS_DIAGRAMS tag to NO.

-CLASS_GRAPH = YES
+CLASS_GRAPH = NO

 # If the COLLABORATION_GRAPH and HAVE_DOT tags are 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.

-COLLABORATION_GRAPH = YES
+COLLABORATION_GRAPH = NO

 # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen 
 # will generate a graph for groups, showing the direct groups dependencies
@@ -1245,7 +1245,7 @@ INCLUDE_GRAPH = YES
 # documented header file showing the documented files that directly or 
 # indirectly include this file.

-INCLUDED_BY_GRAPH = YES
+INCLUDED_BY_GRAPH = NO

 # If the CALL_GRAPH and HAVE_DOT options are set to YES then 
 # doxygen will generate a call dependency graph for every global function 
@@ -1266,7 +1266,7 @@ CALLER_GRAPH = NO
 # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
 # will graphical hierarchy of all classes instead of a textual one.

-GRAPHICAL_HIERARCHY = YES
+GRAPHICAL_HIERARCHY = NO

 # If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES 
 # then doxygen will show the dependencies a directory has on other directories 
@@ -177,6 +177,17 @@ static int cov_encode_subscription(
    return apdu_len;
 }

+/** Handle a request to list all the COV subscriptions.
+ * @ingroup DSCOV
+ *  Invoked by a request to read the Device object's PROP_ACTIVE_COV_SUBSCRIPTIONS.
+ *  Loops through the list of COV Subscriptions, and, for each valid one,
+ *  adds its description to the APDU.
+ *  @note This function needs some work to better handle buffer overruns.
+ *  @param apdu [out] Buffer in which the APDU contents are built.
+ *  @param max_apdu [in] Max length of the APDU buffer.
+ *  @return How many bytes were encoded in the buffer, or -2 if the response
+ *          would not fit within the buffer. 
+ */
 int handler_cov_encode_subscriptions(
    uint8_t * apdu,
    int max_apdu)
@@ -192,6 +203,7 @@ int handler_cov_encode_subscriptions(
                    cov_encode_subscription(&apdu[apdu_len],
                    max_apdu - apdu_len, &COV_Subscriptions[index]);
                apdu_len += len;
+                /* TODO: too late here to notice that we overran the buffer */
                if (apdu_len > max_apdu) {
                    return -2;
                }
@@ -202,6 +214,9 @@ int handler_cov_encode_subscriptions(
    return apdu_len;
 }

+/** Handler to initialize the COV list, clearing and disabling each entry. 
+ * @ingroup DSCOV
+ */
 void handler_cov_init(
    void)
 {
@@ -368,8 +383,27 @@ static bool cov_send_request(
    return status;
 }

-/* note: worst case tasking: MS/TP with the ability to send only
-   one notification per task cycle */
+/** Handler to check the list of subscribed objects for any that have changed 
+ *  and so need to have notifications sent.
+ * @ingroup DSCOV
+ * This handler will be invoked by the main program every second or so.
+ * This example only handles Binary Inputs, but can be easily extended to
+ * support other types.
+ * For each subscribed object,
+ *  - See if the subscription has timed out
+ *    - Remove it if it has timed out.
+ *  - See if the subscribed object instance has changed
+ *    (eg, check with Binary_Input_Change_Of_Value() )
+ *  - If changed,
+ *    - Clear the COV (eg, Binary_Input_Change_Of_Value_Clear() )
+ *    - Send the notice with cov_send_request() 
+ *      - Will be confirmed or unconfirmed, as per the subscription.  
+ *      
+ * @note worst case tasking: MS/TP with the ability to send only
+ *        one notification per task cycle.
+ *        
+ * @param elapsed_seconds [in] How many seconds have elapsed since last called.
+ */
 void handler_cov_task(
    uint32_t elapsed_seconds)
 {
@@ -447,6 +481,23 @@ static bool cov_subscribe(
    return status;
 }

+/** Handler for a COV Subscribe Service request.
+ * @ingroup DSCOV
+ * This handler will be invoked by apdu_handler() if it has been enabled
+ * by a call to apdu_set_confirmed_handler().
+ * This handler builds a response packet, which is
+ * - an Abort if
+ *   - the message is segmented
+ *   - if decoding fails
+ * - an ACK, if cov_subscribe() succeeds
+ * - an Error if cov_subscribe() fails 
+ * 
+ * @param service_request [in] The contents of the service request.
+ * @param service_len [in] The length of the service_request.
+ * @param src [in] BACNET_ADDRESS of the source of the message
+ * @param service_data [in] The BACNET_CONFIRMED_SERVICE_DATA information 
+ *                          decoded from the APDU header of this message. 
+ */
 void handler_cov_subscribe(
    uint8_t * service_request,
    uint16_t service_len,
@@ -6,18 +6,22 @@ To build the Doxygen documentation for the BACnet Stack:
  graphviz installed.
 - To build from the command line, just enter
  doxygen BACnet-stack.doxyfile
- Output is built in doc/output/html and doc/output/latex
- The Latex output can be converted into a PDF (see doxygen manual,
-  google, and good luck!)
+- Output is built in doc/output/html, and there is a convenient
+  starting point at doc/output/BAC_stack.html.
 - If you use Eclipse, 
  - install the eClox plugin to support doxygen within Eclipse
  - Build the documents by right clicking on BACnet-stack.doxyfile,
    and selecting "@ Build Documentation"
 - Feel free to tweak the doxygen output to your tastes, interests, and 
  choice of output formats.
+- The Latex output can be converted into a PDF (see doxygen manual,
+  google, and good luck!)
+- I have tried the PDF, man, and RTF outputs and not liked the results
+  for any of them (500+ pages). I recommend the HTML output, as it is
+  well organized and has an obvious flow, both of which the others lack.
    
 The doxygen output is not checked into this project because it consists of
-  over 10,000 little files (for HTML and Latex), and it is easily 
+  over 5,000 little files (for HTML with call graphs), and it is easily 
  regenerated.
  
 For speed, the function call graphs are not enabled in the SVN version
@@ -0,0 +1,16 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<title>BAC-stack</title>
+</head>
+<frameset cols="250,*">
+  <frame src="html/tree.html" name="treefrm"/>
+  <frame src="html/main.html" name="basefrm"/>
+  <noframes>
+    <body>
+    <a href="html/main.html">Frames are disabled. Click here to go to the main page.</a>
+    </body>
+  </noframes>
+</frameset>
+</html>
@@ -126,4 +126,19 @@ extern "C" {
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
+
+/** @defgroup DSCOV Data Sharing - Change of Value Service (DS-COV)
+ * @ingroup DataShare
+ * 13.1 Change of Value Reporting <br>
+ * Change of value (COV) reporting allows a COV-client to subscribe with a 
+ * COV-server, on a permanent or temporary basis, to receive reports of some 
+ * changes of value of some referenced property based on fixed criteria. 
+ * If an object provides COV reporting, then changes of value of any 
+ * subscribed-to properties of the object, in some cases based on programmable
+ * increments, trigger COV notifications to be sent to subscribing clients. 
+ * Typically, COV notifications are sent to supervisory programs in COV-client 
+ * devices or to operators or logging devices. Any object, proprietary or 
+ * standard, may support COV reporting at the implementor's option.
+ */
+
 #endif