BACnetStack_AddObject

bool BACnetStack_AddObject(
  const uint32_t deviceInstance,
  const uint16_t objectType,
  const uint32_t objectInstance);

Adds a BACnet object to an existing device.

WHO SERVES WHAT, for every object type created this way.

Handled and stored by the CAS BACnet Stack:

• ObjectIdentifier, ObjectType, PropertyList
• StatusFlags - the stack ASSEMBLES the bitstring, but reads EventState, Reliability and OutOfService back through your callbacks to do it
• PriorityArray and CurrentCommandPriority for a commandable object - also assembled from your callbacks, see below

Everything else is served by your callbacks. ObjectName is the one every object needs: without CallbackGetPropertyCharacterString the stack answers “Object <type>,<instance>” (for example “Object 0,1” for Analog Input 1), which is unique in the device but not descriptive.

PresentValue is dispatched by the object type’s datatype. Register the matching pair:

    --------------------------------------------------------------------------------
    Property            Datatype            Callback
    --------------------------------------------------------------------------------
    Real                analogInput,        CallbackGetPropertyReal
                        analogOutput,       CallbackSetPropertyReal
                        analogValue,
                        loop, pulseConverter
    Enumerated          binaryInput,        CallbackGetPropertyEnumerated
                        binaryOutput,       CallbackSetPropertyEnumerated
                        binaryValue,
                        lifeSafetyPoint,
                        lifeSafetyZone,
                        accessDoor
    Unsigned            multiStateInput,    CallbackGetPropertyUnsignedInteger
                        multiStateOutput,   CallbackSetPropertyUnsignedInteger
                        multiStateValue,
                        positiveIntegerValue,
                        accumulator, command
    Signed              integerValue        CallbackGetPropertySignedInteger
                                            CallbackSetPropertySignedInteger
    Double              largeAnalogValue    CallbackGetPropertyDouble
                                            CallbackSetPropertyDouble
    Boolean             calendar            CallbackGetPropertyBool
                                            CallbackSetPropertyBool
    CharacterString     characterstringValue
                                            CallbackGetPropertyCharacterString
                                            CallbackSetPropertyCharacterString
    OctetString         octetstringValue    CallbackGetPropertyOctetString
                                            CallbackSetPropertyOctetString
    BitString           bitstringValue      CallbackGetPropertyBitString
                                            CallbackSetPropertyBitString
    Date                dateValue,          CallbackGetPropertyDate
                        datepatternValue    CallbackSetPropertyDate
    Time                timeValue,          CallbackGetPropertyTime
                        timepatternValue    CallbackSetPropertyTime
    DateTime            datetimeValue,      CallbackGetPropertyDate + CallbackGetPropertyTime
                        datetimepatternValue
    --------------------------------------------------------------------------------

COMMANDABLE OBJECTS ARE READ DIFFERENTLY. analogOutput, binaryOutput, multiStateOutput, accessDoor, lightingOutput and binaryLightingOutput are always commandable; the *Value types become commandable once you enable BOTH PriorityArray and RelinquishDefault. For a commandable object the stack NEVER calls the plain PresentValue callback. It reads the priority array instead - CallbackGetPropertyBool for the “is this slot NULL” flag, then the typed getter above for the value - both with propertyIdentifier = PriorityArray, useArrayIndex = true and index 1..16, and it reports the highest-priority non-NULL slot, falling back to RelinquishDefault. For the flag, set *value to true when that slot is NULL (relinquished) and false when it holds a value, and return true. A false return fails the PriorityArray and PresentValue reads with VALUE_NOT_INITIALIZED; errorCode is not used on this path.

DO NOT USE THIS FUNCTION for the object types that have their own constructor. Creating one of these with BACnetStack_AddObject() alone produces an object with no engine behind it:

• notificationClass -> every property read returns Error(OBJECT, UNKNOWN_OBJECT)
• trendLog, trendLogMultiple, eventLog -> reads Abort
• file -> FileAccessMethod is absent and every AtomicReadFile/AtomicWriteFile aborts
• networkPort -> no data link behind it
• elevatorGroup, lift, escalator -> required object-identifier properties are unset and reads Abort And for these three, call BACnetStack_AddObject() FIRST and then the configuration function, or the object exists with no stack data behind it:
• channel -> then BACnetStack_AddChannelObject()
• group -> then BACnetStack_AddGroupObject()
• schedule -> then BACnetStack_AddScheduleObject() A calendar may optionally be handed to the stack the same way (BACnetStack_AddCalendarObject()); without it the host serves Present_Value and Date_List through the callbacks.

A DUPLICATE ADD IS A SILENT SUCCESS: if the object already exists this returns true, adds nothing and does not increment Database_Revision. True does not mean “created”.

objectType must be a standard type this build models (its STACK_OPTION_OBJECT_TYPE_* option is on), the Device type, or a proprietary type (128 to 1023). A standard type the build does not model - its option is off, the standard removed it (Network Security, 38) or the number is not an assigned standard type - is refused and returns false. Past that check the type is marked supported - and so appears in the device’s Protocol_Object_Types_Supported - BEFORE the duplicate check, so even a no-op call marks the type.

Object types that need extra configuration have their own constructors (BACnetStack_AddTrendLogObject(), BACnetStack_AddFileObject(), BACnetStack_AddNetworkPortObject() and others); use those instead of this function for those types.

See also: BACnetStack_ObjectExists(), BACnetStack_RemoveObject()

Parameters

Parameter	Direction	Description
deviceInstance	in	The device instance of the BACnet device to add the object.
objectType	in	The object type of the BACnet object to add. See CASBACnetStack::BACnetObjectType for more info. With objectInstance, this is one BACnet Object Identifier carried as two parameters (see the API conventions).
objectInstance	in	The object instance of the BACnet object to add. Must be between 0 and 4194302 inclusively (22 bits). 4194303 is the reserved “unknown instance” value and is rejected.

Returns

True if the object exists on the device after the call - whether this call created it or it was already there. False if the device does not exist, objectType or objectInstance is out of range, or objectType is a standard type this build does not model.

Topic: Objects and properties. Declared in CASBACnetStackDLL.h.