diff --git a/bacnet-stack/demo/object/device.c b/bacnet-stack/demo/object/device.c index 073f0beb..b187b36c 100644 --- a/bacnet-stack/demo/object/device.c +++ b/bacnet-stack/demo/object/device.c @@ -23,6 +23,9 @@ * *********************************************************************/ +/** @file device.c Base "class" for handling all BACnet objects belonging + * to a BACnet device, as well as Device-specific properties. */ + #include #include #include /* for memmove */ diff --git a/bacnet-stack/include/device.h b/bacnet-stack/include/device.h index 6a3f19b9..7c3d142e 100644 --- a/bacnet-stack/include/device.h +++ b/bacnet-stack/include/device.h @@ -31,6 +31,10 @@ License. ------------------------------------------- ####COPYRIGHTEND####*/ + +/** @file device.h Defines functions for handling all BACnet objects belonging + * to a BACnet device, as well as Device-specific properties. */ + #ifndef DEVICE_H #define DEVICE_H @@ -44,21 +48,43 @@ #include "rpm.h" #include "readrange.h" +/** Called so a BACnet object can perform any necessary initialization. */ typedef void ( *object_init_function) ( void); + +/** Counts the number of objects of this type. + * @return Count of implemented objects of this type. + */ typedef unsigned ( *object_count_function) ( void); + +/** Maps an object index position to its corresponding BACnet object instance number. + * @param index [in] The index of the object, in the array of objects of its type. + * @return The BACnet object instance number to be used in a BACNET_OBJECT_ID. + */ typedef uint32_t( *object_index_to_instance_function) ( unsigned index); + +/** Provides the BACnet Object_Name for a given object instance of this type. + * @param [in] The object instance number to be looked up. + * @return Pointer to a string containing the unique Object_Name. This string + * is temporary and should be copied upon the return. It is + * allocated by the system and does not need to be freed. + */ typedef char *( *object_name_function) ( uint32_t object_instance); +/** Look in the table of objects of this type, and see if this is a valid + * instance number. + * @param [in] The object instance number to be looked up. + * @return True if the object instance refers to a valid object of this type. + */ typedef bool( *object_valid_instance_function) ( uint32_t object_instance); diff --git a/bacnet-stack/include/readrange.h b/bacnet-stack/include/readrange.h index cd59d216..c6fa103c 100644 --- a/bacnet-stack/include/readrange.h +++ b/bacnet-stack/include/readrange.h @@ -124,8 +124,11 @@ typedef struct rrpropertyinfo { rr_handler_function Handler; } RR_PROP_INFO; -/** Function pointer for ReadRange information retrieval function */ - +/** Function template for ReadRange information retrieval function. + * @param pRequest [in] Info on the request. + * @param pInfo [out] Where to write the response to. + * @return True on success, False on error or failure. + */ typedef bool (*rr_info_function) ( BACNET_READ_RANGE_DATA *pRequest, /* Info on the request */ RR_PROP_INFO *pInfo); /* Where to write the response to */ diff --git a/bacnet-stack/include/rp.h b/bacnet-stack/include/rp.h index 58a249ce..ae76da54 100644 --- a/bacnet-stack/include/rp.h +++ b/bacnet-stack/include/rp.h @@ -50,6 +50,14 @@ typedef struct BACnet_Read_Property_Data { BACNET_ERROR_CODE error_code; } BACNET_READ_PROPERTY_DATA; +/** Reads one property for this object type of a given instance. + * A function template; @see device.c for assignment to object types. + * + * @param rp_data [in] Pointer to the BACnet_Read_Property_Data structure, + * which is packed with the information from the RP request. + * @return The length of the apdu encoded or -1 for error or + * -2 for abort message. + */ typedef int ( *read_property_function) ( BACNET_READ_PROPERTY_DATA *rp_data); diff --git a/bacnet-stack/include/rpm.h b/bacnet-stack/include/rpm.h index 393f2e1d..8182d044 100644 --- a/bacnet-stack/include/rpm.h +++ b/bacnet-stack/include/rpm.h @@ -49,6 +49,15 @@ typedef struct BACnet_Read_Access_Data { struct BACnet_Read_Access_Data *next; } BACNET_READ_ACCESS_DATA; +/** Fetches the lists of properties (array of BACNET_PROPERTY_ID's) for this + * object type, grouped by Required, Optional, and Proprietary. + * A function template; @see device.c for assignment to object types. + * + * @param pRequired [out] Pointer reference for the list of Required properties. + * @param pOptional [out] Pointer reference for the list of Optional properties. + * @param pProprietary [out] Pointer reference for the list of Proprietary + * properties for this BACNET_OBJECT_TYPE. + */ typedef void ( *rpm_property_lists_function) ( const int **pRequired, diff --git a/bacnet-stack/include/wp.h b/bacnet-stack/include/wp.h index 51cfb17b..32da35e0 100644 --- a/bacnet-stack/include/wp.h +++ b/bacnet-stack/include/wp.h @@ -55,6 +55,15 @@ typedef struct BACnet_Write_Property_Data { BACNET_ERROR_CODE error_code; } BACNET_WRITE_PROPERTY_DATA; +/** Attempts to write a new value to one property for this object type + * of a given instance. + * A function template; @see device.c for assignment to object types. + * + * @param wp_data [in] Pointer to the BACnet_Write_Property_Data structure, + * which is packed with the information from the WP request. + * @return The length of the apdu encoded or -1 for error or + * -2 for abort message. + */ typedef bool( *write_property_function) ( BACNET_WRITE_PROPERTY_DATA * wp_data);