Doxygenation of the main Alarm/Event and COV functions.

Also documented the main misc functions for handlers.
2010-03-12 03:30:31 +00:00
parent bfd3920698
commit 47ff6200f1
9 changed files with 142 additions and 3 deletions
@@ -37,6 +37,34 @@

 /** @file dlenv.c  Initialize the DataLink configuration. */

+/** Initialize the DataLink configuration from Environment variables, 
+ * or else to defaults.
+ * @ingroup MISCHNDLR
+ * The items configured depend on which BACDL_ the code is built for,
+ * eg, BACDL_BIP. 
+ * 
+ * For most items, checks first for an environment variable, and, if
+ * found, uses that to set the item's value.  Otherwise, will set
+ * to a default value. 
+ * 
+ * The Environment Variables, by BACDL_ type, are:
+ * - BACDL_ALL: (the general-purpose solution)
+ *   - BACNET_DATALINK to set which BACDL_ type we are using.
+ * - (Any):
+ *   - BACNET_APDU_TIMEOUT
+ *   - BACNET_IFACE
+ * - BACDL_BIP: (BACnet/IP)
+ *   - BACNET_IP_PORT
+ *   - with BBMD_ENABLED also:
+ *     - BACNET_BBMD_PORT
+ *     - BACNET_BBMD_TIMETOLIVE
+ *     - BACNET_BBMD_ADDRESS
+ * - BACDL_MSTP: (BACnet MS/TP)
+ *   - BACNET_MAX_INFO_FRAMES
+ *   - BACNET_MAX_MASTER
+ *   - BACNET_MSTP_BAUD
+ *   - BACNET_MSTP_MAC
+ */
 void dlenv_init(
    void)
 {
@@ -39,6 +39,22 @@

 /** @file h_alarm_ack.c  Handles Alarm Acknowledgment. */

+/** Handler for an Alarm/Event Acknowledgement.
+ * @ingroup ALMACK
+ * 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
+ * - Otherwise, sends a simple ACK
+ * 
+ * @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_alarm_ack(
    uint8_t * service_request,
    uint16_t service_len,
@@ -44,8 +44,18 @@

 /** @file h_ucov.c  Handles Unconfirmed COV Notifications. */

-/* note: nothing is specified in BACnet about what to do with the
-  information received from Unconfirmed COV Notifications. */
+/*  */
+/** Handler for an Unconfirmed COV Notification.
+ * @ingroup DSCOV
+ * Decodes the received list of Properties to update,
+ * and print them out with the subscription information. 
+ * @note Nothing is specified in BACnet about what to do with the
+ *       information received from Unconfirmed COV Notifications.
+ * 
+ * @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 (unused)
+ */
 void handler_ucov_notification(
    uint8_t * service_request,
    uint16_t service_len,
@@ -36,6 +36,17 @@

 /** @file noserv.c  Handles an unrecognized/unsupported service. */

+/** Handler to be invoked when a Service request is received for which no 
+ *  handler has been defined.
+ * @ingroup MISCHNDLR
+ * This handler builds a Reject response packet, and sends it.
+ * 
+ * @param service_request [in] The contents of the service request (unused).
+ * @param service_len [in] The length of the service_request (unused).
+ * @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_unrecognized_service(
    uint8_t * service_request,
    uint16_t service_len,
@@ -36,7 +36,14 @@

 /** @file s_cevent.c  Send a ConfirmedEventNotification Request. */

-/* returns the invoke id, 0=unsuccessful */
+/** Sends an Confirmed Alarm/Event Notification.
+ * @ingroup EVNOTFCN
+ *  
+ * @param device_id [in] ID of the destination device
+ * @param data [in] The information about the Event to be sent.
+ * @return invoke id of outgoing message, or 0 if communication is disabled,
+ *         or no tsm slot is available. 
+ */
 uint8_t Send_CEvent_Notify(
    uint32_t device_id,
    BACNET_EVENT_NOTIFICATION_DATA * data)
@@ -64,6 +64,13 @@ int ucov_notify_encode_pdu(
    return pdu_len;
 }

+/** Sends an Unconfirmed COV Notification.
+ * @ingroup DSCOV
+ *  
+ * @param buffer [in,out] The buffer to build the message in for sending.
+ * @param cov_data [in]  The COV update information to be encoded.
+ * @return Size of the message sent (bytes), or a negative value on error.
+ */
 int Send_UCOV_Notify(
    uint8_t * buffer,
    BACNET_COV_DATA * cov_data)
@@ -79,6 +86,14 @@ int Send_UCOV_Notify(
    return bytes_sent;
 }

+/** Sends a COV Subscription request.
+ * @ingroup DSCOV
+ *  
+ * @param device_id [in] ID of the destination device
+ * @param cov_data [in]  The COV subscription information to be encoded.
+ * @return invoke id of outgoing message, or 0 if communication is disabled or
+ *         no slot is available from the tsm for sending.
+ */
 uint8_t Send_COV_Subscribe(
    uint32_t device_id,
    BACNET_SUBSCRIBE_COV_DATA * cov_data)
@@ -30,6 +30,14 @@

 /** @file s_uevent.c  Send an Unconfirmed Event Notification. */

+/** Sends an Unconfirmed Alarm/Event Notification.
+ * @ingroup EVNOTFCN
+ *  
+ * @param buffer [in,out] The buffer to build the message in for sending.
+ * @param data [in] The information about the Event to be sent.
+ * @param dest [in] The destination address information (may be a broadcast).
+ * @return Size of the message sent (bytes), or a negative value on error.
+ */
 int Send_UEvent_Notify(
    uint8_t * buffer,
    BACNET_EVENT_NOTIFICATION_DATA * data,
@@ -209,4 +209,42 @@ extern "C" {
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
+
+/** @defgroup ALMEVNT Alarm and Event Management BIBBs
+ * These BIBBs prescribe the BACnet capabilities required to interoperably 
+ * perform the alarm and event management functions enumerated in 22.2.1.2 
+ * for the BACnet devices defined therein.
+ */
+
+/** @defgroup EVNOTFCN Alarm and Event-Notification (AE-N)
+ * @ingroup ALMEVNT
+ * 13.6 ConfirmedCOVNotification Service <br>
+ * The ConfirmedCOVNotification service is used to notify subscribers about 
+ * changes that may have occurred to the properties of a particular object. 
+ * Subscriptions for COV notifications are made using the SubscribeCOV service 
+ * or the SubscribeCOVProperty service.
+ * 
+ * 13.7 UnconfirmedCOVNotification Service <br>
+ * The UnconfirmedCOVNotification Service is used to notify subscribers about 
+ * changes that may have occurred to the properties of a particular object, 
+ * or to distribute object properties of wide interest (such as outside air 
+ * conditions) to many devices simultaneously without a subscription. 
+ * Subscriptions for COV notifications are made using the SubscribeCOV service. 
+ * For unsubscribed notifications, the algorithm for determining when to issue 
+ * this service is a local matter and may be based on a change of value, 
+ * periodic updating, or some other criteria.
+ */
+
+/** @defgroup ALMACK  Alarm and Event-ACK (AE-ACK)
+ * @ingroup ALMEVNT
+ * 13.5 AcknowledgeAlarm Service <br>
+ * In some systems a device may need to know that an operator has seen the alarm 
+ * notification. The AcknowledgeAlarm service is used by a notification-client 
+ * to acknowledge that a human operator has seen and responded to an event 
+ * notification with 'AckRequired' = TRUE. Ensuring that the acknowledgment 
+ * actually comes from a person with appropriate authority is a local matter. 
+ * This service may be used in conjunction with either the 
+ * ConfirmedEventNotification service or the UnconfirmedEventNotification service.
+ */
+
 #endif /* BACNET_EVENT_H_ */
@@ -250,4 +250,10 @@ extern "C" {
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
+
+/** @defgroup MISCHNDLR Miscellaneous Handler Utilities
+ * Various utilities and functions to support the Handlers.
+ */
+
+
 #endif