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(%(BACnet_Param_String_Size)d, "%(BACnet_Device_Name)s")     /* Device name         */

   165

#define MAX_DEV_LOC_LEN  STRLEN_X(%(BACnet_Param_String_Size)d, BACNET_DEVICE_LOCATION)       /* Device location     */

   166

#define MAX_DEV_MOD_LEN  STRLEN_X(%(BACnet_Param_String_Size)d, BACNET_DEVICE_MODEL_NAME)     /* Device model name   */

   167

#define MAX_DEV_VER_LEN  STRLEN_X(%(BACnet_Param_String_Size)d, BACNET_DEVICE_APPSOFT_VER)    /* Device application software version */

   168

#define MAX_DEV_DESC_LEN STRLEN_X(%(BACnet_Param_String_Size)d, BACNET_DEVICE_DESCRIPTION)    /* Device description  */

   169

   170

   171

/** Structure to define the Object Properties common to all Objects. */

   172

typedef struct commonBacObj_s {

   173

   174

    /** The BACnet type of this object (ie, what class is this object from?).

   175

     * This property, of type BACnetObjectType, indicates membership in a

   176

     * particular object type class. Each inherited class will be of one type.

   177

     */

   178

    BACNET_OBJECT_TYPE mObject_Type;

   179

   180

    /** The instance number for this class instance. */

   181

    uint32_t Object_Instance_Number;

   182

   183

    /** Object Name; must be unique.

   184

     * This property, of type CharacterString, shall represent a name for

   185

     * the object that is unique within the BACnet Device that maintains it.

   186

     */

   187

    char Object_Name[MAX_DEV_NAME_LEN];

   188

   189

} COMMON_BAC_OBJECT;

   190

   191

   192

/** Structure to define the Properties of Device Objects which distinguish

   193

 *  one instance from another.

   194

 *  This structure only defines fields for properties that are unique to

   195

 *  a given Device object.  The rest may be fixed in device.c or hard-coded

   196

 *  into the read-property encoding.

   197

 *  This may be useful for implementations which manage multiple Devices,

   198

 *  eg, a Gateway.

   199

 */

   200

typedef struct devObj_s {

   201

    /** The BACnet Device Address for this device; ->len depends on DLL type. */

   202

    BACNET_ADDRESS bacDevAddr;

   203

   204

    /** Structure for the Object Properties common to all Objects. */

   205

    COMMON_BAC_OBJECT bacObj;

   206

   207

    /** Device Description. */

   208

    char Description[MAX_DEV_DESC_LEN];

   209

   210

    /** The upcounter that shows if the Device ID or object structure has changed. */

   211

    uint32_t Database_Revision;

   212

} DEVICE_OBJECT_DATA;

   213

   214

   215

#ifdef __cplusplus

   216

extern "C" {

   217

#endif /* __cplusplus */

   218

   219

    void Device_Init(

   220

        const char * Device_Object_Name);

   221

   222

    bool Device_Reinitialize(

   223

        BACNET_REINITIALIZE_DEVICE_DATA * rd_data);

   224

   225

    BACNET_REINITIALIZED_STATE Device_Reinitialized_State(

   226

        void);

   227

   228

    rr_info_function Device_Objects_RR_Info(

   229

        BACNET_OBJECT_TYPE object_type);

   230

   231

    void Device_getCurrentDateTime(

   232

        BACNET_DATE_TIME * DateTime);

   233

    int32_t Device_UTC_Offset(void);

   234

    bool Device_Daylight_Savings_Status(void);

   235

   236

    void Device_Property_Lists(

   237

        const int **pRequired,

   238

        const int **pOptional,

   239

        const int **pProprietary);

   240

    void Device_Objects_Property_List(

   241

        BACNET_OBJECT_TYPE object_type,

   242

        struct special_property_list_t *pPropertyList);

   243

    /* functions to support COV */

   244

    bool Device_Encode_Value_List(

   245

        BACNET_OBJECT_TYPE object_type,

   246

        uint32_t object_instance,

   247

        BACNET_PROPERTY_VALUE * value_list);

   248

    bool Device_Value_List_Supported(

   249

        BACNET_OBJECT_TYPE object_type);

   250

    bool Device_COV(

   251

        BACNET_OBJECT_TYPE object_type,

   252

        uint32_t object_instance);

   253

    void Device_COV_Clear(

   254

        BACNET_OBJECT_TYPE object_type,

   255

        uint32_t object_instance);

   256

   257

    uint32_t Device_Object_Instance_Number(

   258

        void);

   259

    bool Device_Set_Object_Instance_Number(

   260

        uint32_t object_id);

   261

    bool Device_Valid_Object_Instance_Number(

   262

        uint32_t object_id);

   263

    unsigned Device_Object_List_Count(

   264

        void);

   265

    bool Device_Object_List_Identifier(

   266

        unsigned array_index,

   267

        int *object_type,

   268

        uint32_t * instance);

   269

   270

    unsigned Device_Count(

   271

        void);

   272

    uint32_t Device_Index_To_Instance(

   273

        unsigned index);

   274

   275

    bool Device_Object_Name(

   276

        uint32_t object_instance,

   277

        BACNET_CHARACTER_STRING * object_name);

   278

    bool Device_Set_Object_Name(

   279

        BACNET_CHARACTER_STRING * object_name);

   280

    /* Copy a child object name, given its ID. */

   281

    bool Device_Object_Name_Copy(

   282

        BACNET_OBJECT_TYPE object_type,

   283

        uint32_t object_instance,

   284

        BACNET_CHARACTER_STRING * object_name);

   285

    bool Device_Object_Name_ANSI_Init(const char * value);

   286

   287

    BACNET_DEVICE_STATUS Device_System_Status(

   288

        void);

   289

    int Device_Set_System_Status(

   290

        BACNET_DEVICE_STATUS status,

   291

        bool local);

   292

   293

    const char *Device_Vendor_Name(

   294

        void);

   295

   296

    uint16_t Device_Vendor_Identifier(

   297

        void);

   298

    void Device_Set_Vendor_Identifier(

   299

        uint16_t vendor_id);

   300

   301

    const char *Device_Model_Name(

   302

        void);

   303

    bool Device_Set_Model_Name(

   304

        const char *name,

   305

        size_t length);

   306

   307

    const char *Device_Firmware_Revision(

   308

        void);

   309

   310

    const char *Device_Application_Software_Version(

   311

        void);

   312

    bool Device_Set_Application_Software_Version(

   313

        const char *name,

   314

        size_t length);

   315

   316

    const char *Device_Description(

   317

        void);

   318

    bool Device_Set_Description(

   319

        const char *name,

   320

        size_t length);

   321

   322

    const char *Device_Location(

   323

        void);

   324

    bool Device_Set_Location(

   325

        const char *name,

   326

        size_t length);

   327

   328

    /* some stack-centric constant values - no set methods */

   329

    uint8_t Device_Protocol_Version(

   330

        void);

   331

    uint8_t Device_Protocol_Revision(

   332

        void);

   333

    BACNET_SEGMENTATION Device_Segmentation_Supported(

   334

        void);

   335

   336

    uint32_t Device_Database_Revision(

   337

        void);

   338

    void Device_Set_Database_Revision(

   339

        uint32_t revision);

   340

    void Device_Inc_Database_Revision(

   341

        void);

   342

   343

    bool Device_Valid_Object_Name(

   344

        BACNET_CHARACTER_STRING * object_name,

   345

        int *object_type,

   346

        uint32_t * object_instance);

   347

    bool Device_Valid_Object_Id(

   348

        int object_type,

   349

        uint32_t object_instance);

   350

   351

    int Device_Read_Property(

   352

        BACNET_READ_PROPERTY_DATA * rpdata);

   353

    bool Device_Write_Property(

   354

        BACNET_WRITE_PROPERTY_DATA * wp_data);

   355

   356

    bool DeviceGetRRInfo(

   357

        BACNET_READ_RANGE_DATA * pRequest,      /* Info on the request */

   358

        RR_PROP_INFO * pInfo);  /* Where to put the information */

   359

   360

    int Device_Read_Property_Local(

   361

        BACNET_READ_PROPERTY_DATA * rpdata);

   362

    bool Device_Write_Property_Local(

   363

        BACNET_WRITE_PROPERTY_DATA * wp_data);

   364

   365

   366

   367

#ifdef __cplusplus

   368

}

   369

#endif /* __cplusplus */

   370

#endif