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