|
1 /************************************************************************** |
|
2 * |
|
3 * Copyright (C) 2005 Steve Karg <skarg@users.sourceforge.net> |
|
4 * Copyright (C) 2017 Mario de Sousa <msousa@fe.up.pt> |
|
5 * |
|
6 * Permission is hereby granted, free of charge, to any person obtaining |
|
7 * a copy of this software and associated documentation files (the |
|
8 * "Software"), to deal in the Software without restriction, including |
|
9 * without limitation the rights to use, copy, modify, merge, publish, |
|
10 * distribute, sublicense, and/or sell copies of the Software, and to |
|
11 * permit persons to whom the Software is furnished to do so, subject to |
|
12 * the following conditions: |
|
13 * |
|
14 * The above copyright notice and this permission notice shall be included |
|
15 * in all copies or substantial portions of the Software. |
|
16 * |
|
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
|
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
|
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
|
20 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
|
21 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, |
|
22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
|
23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
|
24 * |
|
25 *********************************************************************/ |
|
26 |
|
27 /** device.h Defines functions for handling all BACnet objects belonging |
|
28 * to a BACnet device, as well as Device-specific properties. */ |
|
29 |
|
30 #ifndef DEVICE_H |
|
31 #define DEVICE_H |
|
32 |
|
33 #include <stdbool.h> |
|
34 #include <stdint.h> |
|
35 #include "bacdef.h" |
|
36 #include "bacenum.h" |
|
37 #include "wp.h" |
|
38 #include "rd.h" |
|
39 #include "rp.h" |
|
40 #include "rpm.h" |
|
41 #include "readrange.h" |
|
42 |
|
43 /** Called so a BACnet object can perform any necessary initialization. |
|
44 */ |
|
45 typedef void ( |
|
46 *object_init_function) ( |
|
47 void); |
|
48 |
|
49 /** Counts the number of objects of this type. |
|
50 * return: Count of implemented objects of this type. |
|
51 */ |
|
52 typedef unsigned ( |
|
53 *object_count_function) ( |
|
54 void); |
|
55 |
|
56 /** Maps an object index position to its corresponding BACnet object instance number. |
|
57 * param: index [in] The index of the object, in the array of objects of its type. |
|
58 * return: The BACnet object instance number to be used in a BACNET_OBJECT_ID. |
|
59 */ |
|
60 typedef uint32_t( |
|
61 *object_index_to_instance_function) |
|
62 ( |
|
63 unsigned index); |
|
64 |
|
65 /** Provides the BACnet Object_Name for a given object instance of this type. |
|
66 * param: object_instance [in] The object instance number to be looked up. |
|
67 * param: object_name [in,out] Pointer to a character_string structure that |
|
68 * will hold a copy of the object name if this is a valid object_instance. |
|
69 * return: True if the object_instance is valid and object_name has been |
|
70 * filled with a copy of the Object's name. |
|
71 */ |
|
72 typedef bool( |
|
73 *object_name_function) |
|
74 ( |
|
75 uint32_t object_instance, |
|
76 BACNET_CHARACTER_STRING * object_name); |
|
77 |
|
78 /** Look in the table of objects of this type, and see if this is a valid |
|
79 * instance number. |
|
80 * param: [in] The object instance number to be looked up. |
|
81 * return: True if the object instance refers to a valid object of this type. |
|
82 */ |
|
83 typedef bool( |
|
84 *object_valid_instance_function) ( |
|
85 uint32_t object_instance); |
|
86 |
|
87 /** Helper function to step through an array of objects and find either the |
|
88 * first one or the next one of a given type. Used to step through an array |
|
89 * of objects which is not necessarily contiguious for each type i.e. the |
|
90 * index for the 'n'th object of a given type is not necessarily 'n'. |
|
91 * param: [in] The index of the current object or a value of ~0 to indicate |
|
92 * start at the beginning. |
|
93 * return: The index of the next object of the required type or ~0 (all bits |
|
94 * == 1) to indicate no more objects found. |
|
95 */ |
|
96 typedef unsigned ( |
|
97 *object_iterate_function) ( |
|
98 unsigned current_index); |
|
99 |
|
100 /** Look in the table of objects of this type, and get the COV Value List. |
|
101 * param: [in] The object instance number to be looked up. |
|
102 * param: [out] The value list |
|
103 * return: True if the object instance supports this feature, and has changed. |
|
104 */ |
|
105 typedef bool( |
|
106 *object_value_list_function) ( |
|
107 uint32_t object_instance, |
|
108 BACNET_PROPERTY_VALUE * value_list); |
|
109 |
|
110 /** Look in the table of objects for this instance to see if value changed. |
|
111 * param: [in] The object instance number to be looked up. |
|
112 * return: True if the object instance has changed. |
|
113 */ |
|
114 typedef bool( |
|
115 *object_cov_function) ( |
|
116 uint32_t object_instance); |
|
117 |
|
118 /** Look in the table of objects for this instance to clear the changed flag. |
|
119 * param: [in] The object instance number to be looked up. |
|
120 */ |
|
121 typedef void ( |
|
122 *object_cov_clear_function) ( |
|
123 uint32_t object_instance); |
|
124 |
|
125 /** Intrinsic Reporting funcionality. |
|
126 * param: [in] Object instance. |
|
127 */ |
|
128 typedef void ( |
|
129 *object_intrinsic_reporting_function) ( |
|
130 uint32_t object_instance); |
|
131 |
|
132 |
|
133 /** Defines the group of object helper functions for any supported Object. |
|
134 * Each Object must provide some implementation of each of these helpers |
|
135 * in order to properly support the handlers. Eg, the ReadProperty handler |
|
136 * handler_read_property() relies on the instance of Object_Read_Property |
|
137 * for each Object type, or configure the function as NULL. |
|
138 * In both appearance and operation, this group of functions acts like |
|
139 * they are member functions of a C++ Object base class. |
|
140 */ |
|
141 typedef struct object_functions { |
|
142 BACNET_OBJECT_TYPE Object_Type; |
|
143 object_init_function Object_Init; |
|
144 object_count_function Object_Count; |
|
145 object_index_to_instance_function Object_Index_To_Instance; |
|
146 object_valid_instance_function Object_Valid_Instance; |
|
147 object_name_function Object_Name; |
|
148 read_property_function Object_Read_Property; |
|
149 write_property_function Object_Write_Property; |
|
150 rpm_property_lists_function Object_RPM_List; |
|
151 rr_info_function Object_RR_Info; |
|
152 object_iterate_function Object_Iterator; |
|
153 object_value_list_function Object_Value_List; |
|
154 object_cov_function Object_COV; |
|
155 object_cov_clear_function Object_COV_Clear; |
|
156 object_intrinsic_reporting_function Object_Intrinsic_Reporting; |
|
157 } object_functions_t; |
|
158 |
|
159 /* String Lengths for Device Object properties that may be changed |
|
160 * (written to) over the BACnet network. |
|
161 * Maximum sizes excluding nul terminator . |
|
162 */ |
|
163 #define STRLEN_X(minlen, str) (((minlen)>sizeof(str))?(minlen):sizeof(str)) |
|
164 #define MAX_DEV_NAME_LEN STRLEN_X(32, "%(BACnet_Device_Name)s") /* Device name */ |
|
165 #define MAX_DEV_LOC_LEN STRLEN_X(64, BACNET_DEVICE_LOCATION) /* Device location */ |
|
166 #define MAX_DEV_MOD_LEN STRLEN_X(32, BACNET_DEVICE_MODEL_NAME) /* Device model name */ |
|
167 #define MAX_DEV_VER_LEN STRLEN_X(16, BACNET_DEVICE_APPSOFT_VER) /* Device application software version */ |
|
168 #define MAX_DEV_DESC_LEN STRLEN_X(64, BACNET_DEVICE_DESCRIPTION) /* Device description */ |
|
169 |
|
170 /** Structure to define the Object Properties common to all Objects. */ |
|
171 typedef struct commonBacObj_s { |
|
172 |
|
173 /** The BACnet type of this object (ie, what class is this object from?). |
|
174 * This property, of type BACnetObjectType, indicates membership in a |
|
175 * particular object type class. Each inherited class will be of one type. |
|
176 */ |
|
177 BACNET_OBJECT_TYPE mObject_Type; |
|
178 |
|
179 /** The instance number for this class instance. */ |
|
180 uint32_t Object_Instance_Number; |
|
181 |
|
182 /** Object Name; must be unique. |
|
183 * This property, of type CharacterString, shall represent a name for |
|
184 * the object that is unique within the BACnet Device that maintains it. |
|
185 */ |
|
186 char Object_Name[MAX_DEV_NAME_LEN]; |
|
187 |
|
188 } COMMON_BAC_OBJECT; |
|
189 |
|
190 |
|
191 /** Structure to define the Properties of Device Objects which distinguish |
|
192 * one instance from another. |
|
193 * This structure only defines fields for properties that are unique to |
|
194 * a given Device object. The rest may be fixed in device.c or hard-coded |
|
195 * into the read-property encoding. |
|
196 * This may be useful for implementations which manage multiple Devices, |
|
197 * eg, a Gateway. |
|
198 */ |
|
199 typedef struct devObj_s { |
|
200 /** The BACnet Device Address for this device; ->len depends on DLL type. */ |
|
201 BACNET_ADDRESS bacDevAddr; |
|
202 |
|
203 /** Structure for the Object Properties common to all Objects. */ |
|
204 COMMON_BAC_OBJECT bacObj; |
|
205 |
|
206 /** Device Description. */ |
|
207 char Description[MAX_DEV_DESC_LEN]; |
|
208 |
|
209 /** The upcounter that shows if the Device ID or object structure has changed. */ |
|
210 uint32_t Database_Revision; |
|
211 } DEVICE_OBJECT_DATA; |
|
212 |
|
213 |
|
214 #ifdef __cplusplus |
|
215 extern "C" { |
|
216 #endif /* __cplusplus */ |
|
217 |
|
218 void Device_Init( |
|
219 const char * Device_Object_Name); |
|
220 |
|
221 bool Device_Reinitialize( |
|
222 BACNET_REINITIALIZE_DEVICE_DATA * rd_data); |
|
223 |
|
224 BACNET_REINITIALIZED_STATE Device_Reinitialized_State( |
|
225 void); |
|
226 |
|
227 rr_info_function Device_Objects_RR_Info( |
|
228 BACNET_OBJECT_TYPE object_type); |
|
229 |
|
230 void Device_getCurrentDateTime( |
|
231 BACNET_DATE_TIME * DateTime); |
|
232 int32_t Device_UTC_Offset(void); |
|
233 bool Device_Daylight_Savings_Status(void); |
|
234 |
|
235 void Device_Property_Lists( |
|
236 const int **pRequired, |
|
237 const int **pOptional, |
|
238 const int **pProprietary); |
|
239 void Device_Objects_Property_List( |
|
240 BACNET_OBJECT_TYPE object_type, |
|
241 struct special_property_list_t *pPropertyList); |
|
242 /* functions to support COV */ |
|
243 bool Device_Encode_Value_List( |
|
244 BACNET_OBJECT_TYPE object_type, |
|
245 uint32_t object_instance, |
|
246 BACNET_PROPERTY_VALUE * value_list); |
|
247 bool Device_Value_List_Supported( |
|
248 BACNET_OBJECT_TYPE object_type); |
|
249 bool Device_COV( |
|
250 BACNET_OBJECT_TYPE object_type, |
|
251 uint32_t object_instance); |
|
252 void Device_COV_Clear( |
|
253 BACNET_OBJECT_TYPE object_type, |
|
254 uint32_t object_instance); |
|
255 |
|
256 uint32_t Device_Object_Instance_Number( |
|
257 void); |
|
258 bool Device_Set_Object_Instance_Number( |
|
259 uint32_t object_id); |
|
260 bool Device_Valid_Object_Instance_Number( |
|
261 uint32_t object_id); |
|
262 unsigned Device_Object_List_Count( |
|
263 void); |
|
264 bool Device_Object_List_Identifier( |
|
265 unsigned array_index, |
|
266 int *object_type, |
|
267 uint32_t * instance); |
|
268 |
|
269 unsigned Device_Count( |
|
270 void); |
|
271 uint32_t Device_Index_To_Instance( |
|
272 unsigned index); |
|
273 |
|
274 bool Device_Object_Name( |
|
275 uint32_t object_instance, |
|
276 BACNET_CHARACTER_STRING * object_name); |
|
277 bool Device_Set_Object_Name( |
|
278 BACNET_CHARACTER_STRING * object_name); |
|
279 /* Copy a child object name, given its ID. */ |
|
280 bool Device_Object_Name_Copy( |
|
281 BACNET_OBJECT_TYPE object_type, |
|
282 uint32_t object_instance, |
|
283 BACNET_CHARACTER_STRING * object_name); |
|
284 bool Device_Object_Name_ANSI_Init(const char * value); |
|
285 |
|
286 BACNET_DEVICE_STATUS Device_System_Status( |
|
287 void); |
|
288 int Device_Set_System_Status( |
|
289 BACNET_DEVICE_STATUS status, |
|
290 bool local); |
|
291 |
|
292 const char *Device_Vendor_Name( |
|
293 void); |
|
294 |
|
295 uint16_t Device_Vendor_Identifier( |
|
296 void); |
|
297 void Device_Set_Vendor_Identifier( |
|
298 uint16_t vendor_id); |
|
299 |
|
300 const char *Device_Model_Name( |
|
301 void); |
|
302 bool Device_Set_Model_Name( |
|
303 const char *name, |
|
304 size_t length); |
|
305 |
|
306 const char *Device_Firmware_Revision( |
|
307 void); |
|
308 |
|
309 const char *Device_Application_Software_Version( |
|
310 void); |
|
311 bool Device_Set_Application_Software_Version( |
|
312 const char *name, |
|
313 size_t length); |
|
314 |
|
315 const char *Device_Description( |
|
316 void); |
|
317 bool Device_Set_Description( |
|
318 const char *name, |
|
319 size_t length); |
|
320 |
|
321 const char *Device_Location( |
|
322 void); |
|
323 bool Device_Set_Location( |
|
324 const char *name, |
|
325 size_t length); |
|
326 |
|
327 /* some stack-centric constant values - no set methods */ |
|
328 uint8_t Device_Protocol_Version( |
|
329 void); |
|
330 uint8_t Device_Protocol_Revision( |
|
331 void); |
|
332 BACNET_SEGMENTATION Device_Segmentation_Supported( |
|
333 void); |
|
334 |
|
335 uint32_t Device_Database_Revision( |
|
336 void); |
|
337 void Device_Set_Database_Revision( |
|
338 uint32_t revision); |
|
339 void Device_Inc_Database_Revision( |
|
340 void); |
|
341 |
|
342 bool Device_Valid_Object_Name( |
|
343 BACNET_CHARACTER_STRING * object_name, |
|
344 int *object_type, |
|
345 uint32_t * object_instance); |
|
346 bool Device_Valid_Object_Id( |
|
347 int object_type, |
|
348 uint32_t object_instance); |
|
349 |
|
350 int Device_Read_Property( |
|
351 BACNET_READ_PROPERTY_DATA * rpdata); |
|
352 bool Device_Write_Property( |
|
353 BACNET_WRITE_PROPERTY_DATA * wp_data); |
|
354 |
|
355 bool DeviceGetRRInfo( |
|
356 BACNET_READ_RANGE_DATA * pRequest, /* Info on the request */ |
|
357 RR_PROP_INFO * pInfo); /* Where to put the information */ |
|
358 |
|
359 int Device_Read_Property_Local( |
|
360 BACNET_READ_PROPERTY_DATA * rpdata); |
|
361 bool Device_Write_Property_Local( |
|
362 BACNET_WRITE_PROPERTY_DATA * wp_data); |
|
363 |
|
364 |
|
365 |
|
366 #ifdef __cplusplus |
|
367 } |
|
368 #endif /* __cplusplus */ |
|
369 #endif |